# 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.