NiBabel Developer Guidelines

Also seeDeveloper documentation page

NiBabel source code

Documentation

Code Documentation

Please write documentation using Numpy documentation conventions:

Git Repository

Layout

The main release branch is calledmaster. This is a merge-only branch.Features finished or updated by some developer are merged from thecorresponding branch intomaster. At a certain point the current state ofmaster is tagged – a release is done.

Only usable feature should end-up inmaster. Ideallymaster should bereleasable at all times.

Additionally, there are distribution branches. They are prefixeddist/and labeled after the packaging target (e.g.debian for a Debian package).If necessary, there can be multiple branches for each distribution target.

dist/debian/proper

Official Debian packaging

dist/debian/dev

Debian packaging of unofficial development snapshots. They do not go into themain Debian archive, but might be distributed through other channels (e.g.NeuroDebian).

Releases are merged into the packaging branches, packaging is updated ifnecessary and the branch gets tagged when a package version is released.Maintenance (as well as backport) releases or branches off from the respectivepackaging tag.

There might be additional branches for each developer, prefixed with initials.Alternatively, several GitHub (or elsewhere) clones might be used.

Commits

Please prefix all commit summaries with one (or more) of the following labels.This should help others to easily classify the commits into meaningfulcategories:

  • BF : bug fix

  • RF : refactoring

  • NF : new feature

  • BW : addresses backward-compatibility

  • OPT : optimization

  • BK : breaks something and/or tests fail

  • PL : making pylint happier

  • DOC: for all kinds of documentation related commits

  • TEST: for adding or changing tests

Merges

For easy tracking of what changes were absorbed during merge, weadvise that you enable merge summaries within git:

git-config merge.summary true

SeeConfigure git for more detail.

Testing

NiBabel usestox to organize our testing and development workflows.tox runs tests in isolated environments that we specify,ensuring that we are able to test across many different environments,and those environments do not depend on our local configurations.

If you have thepipx tool installed, then you may simply:

pipxruntox

Alternatively, you can install tox and run it:

python-mpipinstalltoxtox

This will run the tests in several configurations, with multiple sets ofoptional dependencies.If you have multiple versions of Python installed in your path, it willrepeat the process for each version of Python iin our supported range.It may be useful to pick a particular version for rapid development:

tox-epy311-full-x64

This will run the environment using the Python 3.11 interpreter, with thefull set of optional dependencies that are available for 64-bitinterpreters. If you are using 32-bit Python, replace-x64 with-x86.

Style guide

To ensure code consistency and readability, NiBabel has adopted the followingtools:

  • blue - An auto-formatter that aims to reduce diffs to relevant lines

  • isort_ - An import sorter that groups stdlib, third-party and local imports.

  • flake8 - A style checker that can catch (but generally not fix) commonerrors in code.

  • codespell - A spell checker targeted at source code.

  • pre-commit_ - A pre-commit hook manager that runs the above and variousother checks/fixes.

While some amount of personal preference is involved in selecting andconfiguring auto-formatters, their value lies in largely eliminating theneed to think or argue about style.With pre-commit turned on, you can write in the style that works for you,and the NiBabel style will be adopted prior to the commit.

To apply our style checks uniformly, simply run:

tox-estyle,spellcheck

To fix any issues found:

tox-estyle-fixtox-espellcheck---w

Occasionally, codespell has a false positive. To ignore the suggestion, addthe intended word totool.codespell.ignore-words-list inpyproject.toml.However, the ignore list is a blunt instrument and could cause a legitimatemisspelling to be missed. Consider choosing a word that does not triggercodespell before adding it to the ignore list.

Pre-commit hooks

NiBabel usespre-commit_ to help committers validate their changesbefore committing. To enable these, you can usepipx:

pipxrunpre-commitinstall

Or install and run:

python-mpipinstallpre-commitpre-commitinstall

Changelog

The changelog is located in the toplevel directory of the source tree in theChangelog file. The content of this file should be formatted as restructuredtext to make it easy to put it into manual appendix and on the website.

This changelog should neither replicate the VCS commit log nor thedistribution packaging changelogs (e.g. debian/changelog). It should befocused on the user perspective and is intended to list rather macroscopicand/or important changes to the module, like feature additions or bugfixes inthe algorithms with implications to the performance or validity of results.

It may list references to 3rd party bugtrackers, in case the reported bugsmatch the criteria listed above.

Community guidelines

Please seeour community guidelines.Other projects call these guidelines the “code of conduct”.