Contributing to ivadomed

Introduction

First off, thanks for taking the time to contribute! 🎉

When contributing to this repository, please first discuss the change you wish to make by opening a new Github issue.

Contributions relating to content of the Github repository can be submitted through Github pull requests (PR).

PR for bug fixes or new features should be based on the master branch.

The following Github documentation may be useful:

For external contributors: Please fork this repository, make the desired changes, and open a Pull request to have your code reviewed and merged.

For internal contributor: You can open a branch (see Opening a Branch) directly in this repository. If you don’t have the rights, contact the team leader.

Opening an issue

Issues (bugs, feature requests, or others) can be submitted on our project’s issue page.

Before Submitting a New Issue

Please take a few seconds to search the issue database in case the issue has already been raised.

When reporting an issue, make sure your installation has not been tempered with (and if you can, update to the latest release, maybe the problem was fixed).

Submitting an Issue

Issue Title

Try to have a self-descriptive, meaningful issue title, summarizing the problem you see.

Examples:

  • Crashes during image cropping
  • Add a special mode for multi-class segmentation

Issue Body

Describe the issue and mention the IVADO Medical Imaging version and OS that you are using.

If you experience an error, copy/paste the Terminal output (include your syntax) and please follow these guidelines for clarity:

  • If there is less than 10 lines of text, embed it directly in your comment in Github. Use “~~~” to format as code.
  • If there is 10+ lines, either use an external website such as pastebin (copy/paste your text and include the URL in your comment), or use collapsable Github markdown capabilities.

Add useful information such as screenshots, etc.

If you submit a feature request, provide a usage scenario, imagining how the feature would be used (ideally inputs, a sequence of commands, and a desired outcome). Also provide references to any theoretical work to help the reader better understand the feature.

Opening a Branch

If you are part of the core developer team, you can open a branch directly in this repository. Prefix the branch name with a personal identifier and a forward slash; If the branch you are working on is in response to an issue, provide the issue number; Add some text that make the branch name meaningful.

Examples:

  • ol/100-fixup-lr-scheduler
  • ab/loader-pep8

Developing

Conflicts

Make sure the PR changes are not in conflict with the master branch.

Code style

Please review your changes for styling issues, clarity, according to the PEP8 convention. Correct any code style suggested by an analyzer on your changes. PyCharm has a code analyser integrated or you can use pyflakes.

Do not address your functional changes in the same commits as any styling clean-up you may be doing on existing code.

Documentation and docstrings

If you are implementing a new feature, update the documentation to describe the feature, and comment the code (things that are not trivially understandable from the code) to improve its maintainability.

Make sure to cite any papers, algorithms or articles that can help understand the implementation of the feature. If you are implementing an algorithm described in a paper, add pointers to the section / steps.

Please use the Google style docstrings.

Documentation changes will be uploaded to https://ivadomed.org/ automatically once included in the main repository.

To test your documentation locally, do:

pip install '.[docs]'
cd docs; make html
open build/html/index.html

Testing

Please add tests, especially with new code. Unit tests are located under testing/. They are straightforward to augment, but we understand it’s the extra mile; it would still be appreciated if you provide something lighter (eg. in the commit messages or in the PR or issue text) that demonstrates that an issue was fixed, or a feature is functional.

Consider that if you add test cases, they will ensure that your feature – which you probably care about – does not stop working in the future.

Licensing

Ensure that you are the original author of your changes, and if that is not the case, ensure that the borrowed/adapted code is compatible with the project’s License.

Committing

Commit Titles

Provide a concise and self-descriptive title (avoid > 80 characters). You may “scope” the title using the applicable command name(s), folder or other “module” as a prefix. If a commit is responsible for fixing an issue, post-fix the description with (fixes #ISSUE_NUMBER).

Examples:

testing: add testing function for validation metrics
loader: add timer
documentation: add slice_axis to the config files
model: add HeMIS network

Commit Sequences

Update your branch to be baseline on the latest master if new developments were merged while you were developing. Please prefer rebasing to merging, as explained in this tutorial. Note that if you do rebases after review have started, they will be cancelled, so at this point it may be more appropriate to do a pull.

Clean-up your commit sequence. If your are not familiar with git, this good tutorial on the subject may help you.

Focus on committing 1 logical change at a time. See this article on the subject.

Submitting a Pull Request

PR Title

The PR title is used to automatically generate the Changelog for each new release, so please follow the following rules:

  • Provide a concise and self-descriptive title (see Issue Title).
  • Do not include the applicable issue number in the title, do it in the PR body (see PR Body).
  • If the PR is not ready for review, convert it to a draft.

PR Body

Describe what the PR is about, explain the approach and possible drawbacks. Don’t hesitate to repeat some of the text from the related issue (easier to read than having to click on the link).

If the PR fixes issue(s), indicate it after your introduction: Fixes #XXXX, Fixes #YYYY. Note: it is important to respect the syntax above so that the issue(s) will be closed upon merging the PR.

Work in progress

If your PR is not ready for review yet, you can convert it to a “Draft”, so the team is informed.

A draft pull request is styled differently to clearly indicate that it’s in a draft state. Merging is blocked in draft pull requests. Change the status to “Ready for review” near the bottom of your pull request to remove the draft state and allow merging according to your project’s settings.

Continuous Integration

The PR can’t be merged if Github Actions “Run tests” hasn’t succeeded. If you are familiar with it, consult the test results to fix the problem.

Reviewers

Any changes submitted for inclusion to the master branch will have to go through a review.

Only request a review when you deem the PR as “good to go”. If the PR is not ready for review, convert it to a “Draft”.

Github may suggest you to add particular reviewers to your PR. If that’s the case and you don’t know better, add all of these suggestions. The reviewers will be notified when you add them.

Versioning

The procedure for creating a new ivadomed release is described here.