Software development

Software development#

Introduction#

First off, thanks for taking the time to contribute to one of NeuroPoly’s projects! 🎉

This set of guidelines provides general instruction on how to make any one of the following contributions:

Project-Specific Guidance#

In addition to these general guidelines, several of NeuroPoly’s projects also have a GitHub Wiki for internal developer documentation to provide project-specific guidance:

Repo

Wiki

Contributing

AxonDeepSeg

GitHub Wiki

CONTRIBUTING

IVADOMED

GitHub Wiki

CONTRIBUTING

qMRLab

GitHub Wiki

CONTRIBUTING

Shimming Toolbox

GitHub Wiki

CONTRIBUTING

Spinal Cord Toolbox

GitHub Wiki

Opening an Issue on GitHub#

Issues (bugs, feature requests, or others) can be submitted on each project’s GitHub Issue page. 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).

Issue Title#

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

Examples:

  • Installation failure: problem creating launchers

  • Crashes during image cropping

  • Add a special mode for multi-class segmentation

Issue Body#

Describe the issue and mention the project 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 are < 10 lines of text, embed it directly in your comment in GitHub. Use ```<CODE HERE>``` to format as code.

  • If there are 10+ lines, either use an external website such as pastebin (copy/paste your text and include the URL in your comment), or use collapsible Github markdown capabilities​.

Important

Provide steps to reproduce the issue. First, try to reproduce your issue using publicly-available data. If the error is data-specific, upload a zipped version of the data directly into GitHub (not the full dataset, only what’s required to be able to reproduce the error).

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.

Issue Labels#

Mandatory Labels#

The following labels are mandatory for issues, as they help with triaging and project management:

Label Type

Description

Category

Choose one label that describes the category of issue. (Colour: Dark purple with white text)

Context

Choose one or multiple labels corresponding to the area of the codebase affected by the changes. (Colour: Light purple with dark text)

Priority

Choose one of the three priority labels (high, medium, low) describing the urgency of the issue.

Version Milestone

Groups issues and PRs by release. Each project should always have an open milestone that corresponds to the next upcoming release.

Developing Code#

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 (such as your initials) 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.

For example, if my name is Regina Phalange, and I am working on updating the documentation theme:

rp/new-theme-for-docs

Or if my name is John Doe and I am fixing issue #12 that is related to the registration CLI:

jd/12-registration-cli

Branch 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. To check your code, there are several options:

Note

The PEP8 convention, particularly line lengths, does not apply to markdown and rst/sphinx documentation files (see below).

Important

Please, do not address your functional changes in the same commits as any styling clean-up you may be doing on existing code. This will ease the review process.

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.

For documentation outside the code itself (e.g. in Markdown/.md and reStructured/sphinx/.rst files), do not use the vestigial “80 columns” (or any other arbitrary limit) rule; inside a paragraph, instead of using manual line breaks, keep it on one line, and let the text editors dynamically wrap and naturally display those paragraphs based on the user’s window width. Those documentation source files are mostly meant to be read online with the rendered HTML versions anyway (i.e. not on with a 80 columns terminal with monospaced fonts on a 640x480 screen).

Testing#

If you are modifying an existing feature, please be sure to run the existing test suite for your project to ensure new bugs have not been introduced.

If you are adding a new feature, please be sure to add accompanying tests which verify your feature is functioning correctly.

In both cases, please refer to the GitHub Wiki for your specific project for testing protocols.

If you are using Visual Studio Code as an IDE, below is a tutorial on how to set up its testing features (using Spinal Cord Toolbox as an example).

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 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 one logical change at a time. See this article on the subject.

Submitting a Pull Request (PR)#

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: Example: Fixes #25, #78.

Note

It is important to respect the syntax above so that the issue(s) will be closed upon merging the PR.

PR Labels#

Some NeuroPoly projects require adding labels to pull requests, as they are used to automatically generate a Changelog. Labeling protocols may vary between NeuroPoly projects (default project-specific categories are defined here), but the typical mandatory labels include:

  • Category: Choose one label that describes the category of issue. (Colour: Dark purple with white text)

  • Context: Choose one or multiple labels corresponding to the area of the codebase affected by the changes. (Colour: Light purple with dark text)

  • Version milestone: Groups issues and PRs by release. Each project should always have an open milestone that corresponds to the next upcoming release.

The following labels are strongly recommended when appropriate, as they help with managing releases:

  • Compatibility: If your PR breaks cross-compatibility with a previous stable release of SCT, you should add the label “compatibility”. Changes with this label necessitate a new major release, so please plan accordingly.

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#

Some NeuroPoly projects run automated tests on pull requests via continuous integration (TravisCI, GitHub Actions, and others). Please ensure your pull requests pass all tests. If your pull request is failing, the output of the automated tests can help you debug your changes.

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”.

Note

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.

Working on “Epic” Changes#

If you plan to work on an epic contribution, which would imply large changes to the codebase / functionalities, we recommend two possibilities (which are not mutually exclusive):

  • Open an issue describing the proposed contribution, and label it with the label epic,

  • Open a new project board and add a meaningful description

Once the epic issue or project board is open and describes the overall plan, open small issues and cross-reference them with the epic issue, or add the project label.

The general idea is that each small issue represents an incremental means to achieve the epic goal. The advantage of small issues include:

  • Discussion thread are easier to follow and are more focused;

  • The PR addressing the issue is easier to review (because there is few lines of code);

  • If a regression bug is introduced, it is easier to isolate it;

  • Unit test is easier to write and review (because it covers only few lines of code)

Example of epic issue: “Accommodate microscopy modality in ivadomed”. Examples of small, related issues: “Refactor data loader to accept PNG files”, “Add testing data for microscropy”, “Add tutorial for 2D images”, etc.

Versioning#

Versioning uses the following convention: MAJOR.MINOR.PATCH, where:

Version

Description

PATCH

Use when there are backwards-compatible bug fixes or enhancements, without alteration to Python’s modules or data/binaries.

MINOR

Use 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

Use 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”.

Project-specific release procedure:

Alternatively, you can use date-based format rYYYYMMDD. For example: r20230118.