Contributing to ivadomed¶
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
The following Github documentation may be useful:
- See Using Pull Requests for more information about Pull Requests.
- See Fork A Repo for an introduction to forking a repository.
- See Creating branches for an introduction on branching within GitHub.
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¶
Try to have a self-descriptive, meaningful issue title, summarizing the problem you see.
- Crashes during image cropping
- Add a special mode for multi-class segmentation
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.
Make sure the PR changes are not in conflict with the master branch.
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.
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
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.
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
testing: add testing function for validation metrics loader: add timer documentation: add slice_axis to the config files model: add HeMIS network
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¶
The PR title is used to automatically generate the Changelog for each new release, so please follow the following rules:
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.
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.
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 uses the following convention: MAJOR.MINOR.PATCH, where:
PATCH version when there are backwards-compatible bug fixes or enhancements, without alteration to Python’s modules or data/binaries. MINOR version when there are minor API changes or new functionality in a backwards-compatible manner, or when there are alteration to Python’s modules or data/binaries (which requires to re-run installer for people working on the dev version), MAJOR version when there are major incompatible API changes, Beta releases follow the following convention:
MAJOR.MINOR.PATCH-beta.x (with x = 0, 1, 2, etc.) Stable version is indicated in the file version.txt. For development version (on master), the version is “dev”.