- heudiconv/ is the main Python module where major development is happening, with
major submodules being:
cli/- wrappers and argument parsers bringing the HeuDiConv functionality to the command line.external/- general compatibility layers for external functions HeuDiConv depends on.heuristics/- heuristic evaluators for workflows, pull requests here are particularly welcome.
- docs/ - documentation directory.
- utils/ - helper utilities used during development, testing, and distribution of HeuDiConv.
The preferred way to contribute to the HeuDiConv code base is to fork the main repository on GitHub.
If you are unsure what that means, here is a set-up workflow you may wish to follow:
Fork the project repository on GitHub, by clicking on the “Fork” button near the top of the page — this will create a copy of the repository writeable by your GitHub user.
Set up a clone of the repository on your local machine and connect it to both the “official” and your copy of the repository on GitHub:
git clone git://github.com/nipy/heudiconv cd heudiconv git remote rename origin official git remote add origin git://github.com/YOUR_GITHUB_USERNAME/heudiconv
When you wish to start a new contribution, create a new branch:
git checkout -b topic_of_your_contribution
When you are done making the changes you wish to contribute, record them in Git:
git add the/paths/to/files/you/modified can/be/more/than/one git commit
Push the changes to your copy of the code on GitHub, following which Git will provide you with a link which you can click to initiate a pull request:
git push -u origin topic_of_your_contribution
(If any of the above seems overwhelming, you can look up the Git documentation on the web.)
HeuDiConv uses the auto tool to generate the changelog and automatically release the project.
auto is used in the HeuDiConv GitHub actions, which monitors the labels on the pull request. HeuDiConv automation can add entries to the changelog, cut releases, and push new images to dockerhub.
The following pull request labels are respected:
- major: Increment the major version when merged
- minor: Increment the minor version when merged
- patch: Increment the patch version when merged
- skip-release: Preserve the current version when merged
- release: Create a release when this pr is merged
- internal: Changes only affect the internal API
- documentation: Changes only affect the documentation
- tests: Add or improve existing tests
- dependencies: Update one or more dependencies version
- performance: Improve performance of an existing feature
We support Python 3 only (>= 3.7).
Dependencies which you will need are listed in the repository.
Note that you will likely have these will already be available on your system if you used a
package manager (e.g. Debian's apt-get, Gentoo's emerge, or simply PIP) to install the
software.
Development work might require live access to the copy of HeuDiConv which is being developed. If a system-wide release of HeuDiConv is already installed, or likely to be, it is best to keep development work sandboxed inside a dedicated virtual environment. This is best accomplished via:
cd /path/to/your/clone/of/heudiconv mkdir -p venvs/dev python -m venv venvs/dev source venvs/dev/bin/activate pip install -e .[all]
To contribute to the documentation, we recommend building the docs locally prior to submitting a patch.
To build the docs locally:
- From the root of the heudiconv repository, pip install -r docs/requirements.txt
- From the docs/ directory, run make html
It is recommended to check that your contribution complies with the following rules before submitting a pull request:
All public functions (i.e. functions whose name does not start with an underscore) should have informative docstrings with sample usage presented as doctests when appropriate.
Docstrings are formatted in NumPy style.
Lines are no longer than 120 characters.
All tests still pass:
cd /path/to/your/clone/of/heudiconv pytest -vvs .
New code should be accompanied by new tests.