Nilearn maintenance process¶
This section describes how the project is organized.
Nilearn uses issues for tracking bugs, requesting potential features, and holding project discussions.
When creating an issue, the user is responsible for a very basic labeling categorizing the issue:
for bug reports.
for documentation related questions or requests.
for feature requests.
In addition to these basic labels, we have many more labels which describes in more detail a given issue. First, we try to describe the estimated amount of work required to solve each issue:
The issue is likely to require a serious amount of work (more than a couple of days).
The issue is likely to require a decent amount of work (in between a few hours and a couple days).
The issue is likely to require a small amount of work (less than a few hours).
We also try to quantify the estimated impact of the proposed change on the project:
Solving this issue will have a high impact on the project.
Solving this issue will have a decent impact on the project.
Solving this issue will have a small impact on the project.
Finally, we also indicate the priority level of the issue:
The task is urgent and needs to be addressed as soon as possible.
The task is important but not urgent and should be addressed over the next few months.
The task is not urgent and can be delayed.
Some issues—particular those which are low effort and low to medium priority—can serve as good starting project for new contributors. We label these issues with the label which can be seen as an equivalent to a “very low effort” label. Because of this, good first issues do not require a separate effort label.
Other labels can be used to describe further the topic of the issue:
This issue is related to the Nilearn’s API.
This issue tackles code quality (code refactoring, PEP8…).
This issue is related to datasets or the
This issue is used to hold a general discussion on a specific topic where community feedback is desired (no need to specify effort, priority, or impact here).
This issue is related to the
This issue describes a problem with the project’s infrastructure (CI/CD…).
The issue describes a problem with the installation of Nilearn.
This issue is related to maintenance work.
The issue is related to plotting functionalities.
The issue is related to testing.
This issue is a usage question and should have been posted on neurostars.
Finally, we use the following labels to indicate how the work on the issue is going:
Can be used to indicate that this issue is currently being investigated.
Commonly used for tagging PRs, this can be used to indicate that this issue should be solved before the next release.
This issue is currently stalled and has no recent activity. Use this label before closing due to inactivity.
Usually we expect the issue’s author to close the issue, but there are several possible reasons for a community member to close an issue:
The issue has been solved: kindly asked the author whether the issue can be closed. In the absence of reply, close the issue after two weeks.
The issue is a usage question: label the issue with and kindly redirect the author to neurostars. Close the issue afterwards.
The issue has no recent activity (no messages in the last three months): ping the author to see if the issue is still relevant. In the absence of reply, label the issue with and close it after 2 weeks.
This section describes how to make a new release of Nilearn. It is targeted to the specific case of Nilearn although it contains generic steps for packaging and distributing projects. More detailed information can be found on packaging.python.org.
We assume that we are in a clean state where all the Pull Requests (PR) that we wish to include in the new release have been merged. For example, make sure all deprecations that are supposed to be removed with this new version have been addressed. Furthermore, if this new release comes with dependency version bumps (Python, Numpy…), make sure to implement and test these changes beforehand. Ideally, these would have been done before such as to update the code base if necessary. Finally, make sure the documentation can be built correctly.
Switch to a new branch locally:
git checkout -b REL-x.y.z
First we need to prepare the release by updating the file nilearn/doc/whats_new.rst to make sure all the new features, enhancements, and bug fixes are included in their respective sections. We also need to write a “Highlights” section promoting the most important additions that come with this new release, and add the version tag just above the corresponding title:
.. _vx.y.z: x.y.z ===== **Released MONTH YEAR** HIGHLIGHTS ---------- - Nilearn now includes functionality A - ...
Next, we need to bump the version number of Nilearn by updating the file nilearn/version.py with the new version number, that is edit the line:
__version__ = x.y.z.dev
__version__ = x.y.z
We also need to update the website news section by editing the file nilearn/doc/themes/nilearn/layout.html. The news section typically contains links to the last 3 releases that should look like:
<h4> News </h4> <ul> <li><p><strong>November 2020</strong>: <a href="whats_new.html#v0-7-0">Nilearn 0.7.0 released</a> </p></li> <li><p><strong>February 2020</strong>: <a href="whats_new.html#v0-6-2">Nilearn 0.6.2 released</a> </p></li> <li><p><strong>January 2020</strong>: <a href="whats_new.html#v0-6-1">Nilearn 0.6.1 released</a> </p></li> </ul>
Here, we should remove the last entry and add the new release on top of the list.
In addition, we can have a look at MANIFEST.in to check that all additional files that we want to be included or excluded from the release are indicated. Normally we shouldn’t have to touch this file.
Add these changes and submit a PR:
git add doc/whats_new.rst nilearn/version.py git commit -m "REL x.y.z" git push origin REL-x.y.z
Once the PR has been reviewed and merged, pull from master and tag the merge commit:
git checkout master git pull upstream master git tag x.y.z git push upstream --tags
First of all we should make sure we don’t include files that shouldn’t be present:
git checkout x.y.z
If the workspace contains a dist folder, make sure to clean it:
rm -r dist
In order to build the binary wheel files, we need to install wheel:
pip install wheel
And, in order to upload to Pypi, we will use twine that you can also install with pip:
pip install twine
Build the source and binary distributions:
python setup.py sdist bdist_wheel
This should add two files to the dist subfolder:
one for the source distribution that should look like PACKAGENAME-VERSION.tar.gz
one for the built distribution that should look like PACKAGENAME-PACKAGEVERSION-PYTHONVERSION-PYTHONCVERSION-PLATFORM.whl
Optionally, we can run some basic checks with twine:
twine check dist/*
twine upload dist/*
Once the upload is completed, make sure everything looks good on Pypi. Otherwise you will probably have to fix the issue and start over a new release with the patch number incremented.
At this point, we need to upload the binaries to GitHub and link them to the tag. To do so, go to the Nilearn GitHub page under the “Releases” tab, and edit the x.y.z tag by providing a description, and upload the distributions we just created (you can just drag and drop the files).
We now need to update the documentation:
cd doc make install
This will build the documentation (beware, this is time consuming…) and push it to the GitHub pages repo.
At this point, the release has been made. We can now update the file nilearn/version.py and update the version number by increasing the patch number and appending .dev:
__version__ = x.y.(z+1).dev
We can also update the file doc/whats_new.rst by adding a title and the usual New, Enhancements, and Bug Fixes sections for the version currently under development:
x.y.z+1.dev ========= NEW --- Fixes ----- Enhancements ------------ .. _vx.y.z: x.y.z ===== ...