Skip to content

Latest commit

 

History

History
141 lines (92 loc) · 7.8 KB

CONTRIBUTING.md

File metadata and controls

141 lines (92 loc) · 7.8 KB
Raw

NiftyNet

The main source code repository for NiftyNet is CMICLab. The NiftyNet codebase is also mirrored on GitHub.

Submitting bug reports and feature requests

Bug reports and feature requests should be submitted by creating an issue on CMICLab or GitHub.

Submitting merge requests

All merge requests should be submitted via CMICLab or GitHub pull request. Please make sure you have read the following subsections before submitting a merge request.

Python style guide

Please follow the PEP8 Style Guide for Python Code. In particular (from the guide):

Please be consistent. If you're editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.

Testing your changes

Please submit merge requests from your branch to the dev branch.

Before submitting a merge request, please make sure your branch passes all unit tests, by running:

cd NiftyNet/
sh run_test.sh

If you have made changes to the pip installer, please test these. For instance if you have added a new CLI entry point (i.e. a new "command" - also see the respective section below), make sure you include the appropriate tests in the GitLab CI configuration. For an example how to do this please see lines 223 to 270 in the .gitlab-ci.yml file.

Enhancing the pip installer

Adding a new command callable from a pip-installed NiftyNet

This requires added a new console_scripts entry point in the setup.py file. For a practical example see how the net_segment CLI command is implemented. Also see how this command is tested.

Writing unit tests

Please see this README for more information on how to write unit tests for NiftyNet.

NiftyNet admin tasks

Making a release

NiftyNet versions are numbered following Semantic Versioning (semver). After adding notes for the current release to the NiftyNet changelog, the current release should be tagged with a PEP440-compliant semver number preceded by the letter v (for "version").

Bundling a pip installer

The NiftyNet pip installer gets bundled automatically for Git tags starting with a v (for "version") pushed to CMICLab. The wheel version is determined automatically as part of this process. To see how this is done in practice, please go to the pip-camera-ready section of .gitlab-ci.yml (and see the result in this build log - esp. the last few lines lines, which show where the pip installer can be found on the build server).

In particular, bundling a pip installer boils down to running the command python setup.py bdist_wheel in the top-level directory. This creates a wheel binary package in a newly created dist directory, e.g. dist/NiftyNet-0.2.0-py2.py3-none-any.whl.

Publishing a NiftyNet pip installer on PyPI

Making NiftyNet available to the world via a simple pip install niftynet requires publishing the created wheel on the Python Package Index (PyPI). BUT PLEASE TAKE YOUR TIME TO READ THE NOTES BELOW BEFORE PROCEEDING:

  • PyPI is very tightly coupled to package versions. That means, once a wheel tagged e.g. as version 1.0.1 has been published, it is final. In other words, you cannot change your source code, bundle it again using the same version and re-submit to PyPI as the "updated" version 1.0.1.
  • Please consider submitting the bundled wheel to the PyPI test site (see the NiftyNet test page) to assess the visual appearance of the PyPI page before publishing on the actual PyPI.

To actually publish the bundled wheel on PyPI, you will need to run the twine upload command e.g. twine upload dist/NiftyNet-0.2.0-py2.py3-none-any.whl - this will of course work only if you have set the corresponding PyPI account credentials.

Merging GitHub pull requests

The main development hub for NiftyNet is CMICLab. However we would also like to support the GitHub-based workflow in a way that is minimally disruptive to the workflow on CMICLab. For this purpose, please follow the steps below for merging pull requests on GitHub:

  1. [on GitHub] Review the pull request, and ask for changes if needed
  2. [on GitHub] Accept the pull request (i.e. click the "Merge pull request" button)
  3. [on CMICLab] Create a new branch off dev with a name representative of the pull request. For instance merging-github-pr-7 if the pull request on GitHub was numbered 7 (assuming origin is set to [email protected]:CMIC/NiftyNet.git):
    • git checkout -b merging-github-pr-7 origin/dev
  4. [on CMICLab] Pull GitHub's dev branch onto the new branch merging-github-pr-7 you've created (assuming origin is set to [email protected]:CMIC/NiftyNet.git) and push this new branch to CMICLab:
    1. git pull [email protected]:NifTK/NiftyNet.git dev
    2. git push -u origin merging-github-pr-7
  5. [on CMICLab] Make sure merging-github-pr-7 passes all continuous integration tests on CMICLab
  6. [on CMICLab] Merge the new branch merging-github-pr-7 onto dev
  7. [on GitHub] Check that the last step has updated the dev branch mirror