A guide to making a nipy release

A guide for developers who are doing a nipy release

Release checklist

• Review the open list of nipy issues. Check whether there are outstanding issues that can be closed, and whether there are any issues that should delay the release. Label them !

• Review and update the release notes. Review and update the Changelog file. Get a partial list of contributors with something like:

  PREV_RELEASE=0.5.0
  git log $PREV_RELEASE.. | grep '^Author' | cut -d' ' -f 2- | sort | uniq
  

  where 0.5.0 was the last release tag name.

  Then manually go over git shortlog $PREV_RELEASE.. to make sure the release notes are as complete as possible and that every contributor was recognized.

• Use the opportunity to update the .mailmap file if there are any duplicate authors listed from git shortlog -ns.

• Add any new authors to the AUTHOR file. Add any new entries to the THANKS file.

• Check the copyright years in doc/conf.py and LICENSE

• Check the output of:

  rst2html.py README.rst > ~/tmp/readme.html
  

  because this will be the output used by PyPI

• Check the dependencies listed in pyproject.toml and in requirements.txt and in doc/users/installation.rst. They should at least match. Do they still hold? Make sure .github/workflows is testing these minimum dependencies specifically.

• Check the examples. First download the example data by running something like:

  # Install data packages.
  pip install https://nipy.org/data-packages/nipy-templates-0.3.tar.gz
  pip install https://nipy.org/data-packages/nipy-data-0.3.tar.gz
  

  Then run the tests on the examples with:

  # Move out of the source directory.
  cd ..
  # Make log file directory.
  mkdir ~/tmp/eg_logs
  ./nipy/tools/run_log_examples.py nipy/examples --log-path=~/tmp/eg_logs
  

  in a virtualenv. Review the output in (e.g.) ~/tmp/eg_logs. The output file summary.txt will have the pass file printout that the run_log_examples.py script puts onto stdout while running.

• Check the documentation doctests pass:

  virtualenv venv
  venv/bin/activate
  pip install -r doc-requirements.txt
  pip install -e .
  (cd docs && make clean-doctest)
  

• Check the doc build:

  virtualenv venv
  venv/bin/activate
  pip install -r doc-requirements.txt
  pip install -e .
  (cd docs && make html)
  

• Build and test the Nipy wheels. See the wheel builder README for instructions. In summary, clone the wheel-building repo, edit the .github/workflow text files (if present) with the branch or commit for the release, commit and then push back up to github. This will trigger a wheel build and test on macOS, Linux and Windows. Check the build has passed on on the Github interface at https://travis-ci.org/MacPython/nipy-wheels. You’ll need commit privileges to the nipy-wheels repo; ask Matthew Brett or on the mailing list if you do not have them.

Doing the release

• The release should now be ready.

• Edit nipy/__init__.py to set __version__ to e.g. 0.6.0.

  Edit meson.build to set version to match.

  Commit, then:

  make source-release
  

• For the wheel build / upload, follow the wheel builder README instructions again. Push. Check the build has passed on the Github interface. Now follow the instructions in the page above to download the built wheels to a local machine and upload to PyPI.

• Once everything looks good, you are ready to upload the source release to PyPI. See `setuptools intro`_. Make sure you have a file \$HOME/.pypirc, of form:

  [pypi]
  username = __token__
  

• Sign and upload the source release to PyPI using Twine:

  gpg --detach-sign -a dist/nipy*.tar.gz
  twine upload dist/nipy*.tar.gz*
  

• Tag the release with tag of form 0.6.0. -s below makes a signed tag:

  git tag -s 'Second main release' 0.6.0
  

• Now the version number is OK, push the docs to github pages with:

  make upload-html
  

• Start the new series.

  Edit nipy/__init__.py and set version number to something of form:

  __version__ = "0.6.1.dev1"
  

  where 0.6.0 was the previous release.

• Push tags:

  git push --tags
  

• Announce to the mailing lists.