A guide to making a nipy release¶
A guide for developers who are doing a nipy release
Release tools¶
Run:
make check-version-info
This installs the code from a git archive, from the repository, and for
in-place use, and runs the get_info()
function to confirm that
installation is working and information parameters are set correctly. Look for the output at the end, which should look something like:
########
Versions
########
nipy - zip: 0.5.0
nipy - install: 0.5.0
nipy - editable: 0.5.0
where the 0.5.0 should be the version in nipy/info.py.
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:git log 0.2.0.. | grep '^Author' | cut -d' ' -f 2- | sort | uniq
where
0.2.0
was the last release tag name.Then manually go over
git shortlog 0.2.0..
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 fromgit shortlog -ns
.Add any new authors to the
AUTHORS
file. Add any new entries to theTHANKS
file.Check the copyright years in
doc/conf.py
andLICENSE
Refresh the
README.rst
text from theLONG_DESCRIPTION
ininfo.py
by runningmake refresh-readme
.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
nipy/info.py
(e.g.NUMPY_MIN_VERSION
) and inrequirements.txt
and indoc/users/installation.rst
. They should at least match. Do they still hold? Make sure.travis.yml
is testing these minimum dependencies specifically.Check the examples in python 2 and python 3, by running something like:
cd .. ./nipy/tools/run_log_examples.py nipy/examples --log-path=~/tmp/eg_logs
in a Python 2 and python 3 virtualenv. Review the output in (e.g.)
~/tmp/eg_logs
. The output filesummary.txt
will have the pass file printout that therun_log_examples.py
script puts onto stdout while running.You might want to do a by-eye comparison between the 2.7 and 3.x files with:
diff -r nipy-examples-2.7 nipy-examples-3.5 | less
If you have travis-ci_ building set up on your own fork of Nipy you might want to push the code in its current state to a branch that will build, e.g:
git branch -D pre-release-test # in case branch already exists git co -b pre-release-test git push your-github-user pre-release-test
Make sure all the
.c
generated files are up to date with Cython sources with:./tools/nicythize
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
.travis.yml
andappveyor.yml
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 OSX, Linux and Windows. Check the build has passed on on the Travis-CI interface at https://travis-ci.org/MacPython/nipy-wheels. You’ll need commit privileges to thenipy-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/info.py
to set_version_extra
to''
; commit. Then:make source-release
For the wheel build / upload, follow the wheel builder README instructions again. Edit the
.travis.yml
andappveyor.yml
files (if present) to give the release tag to build. Check the build has passed on the Travis-CI interface at https://travis-ci.org/MacPython/nipy-wheels. 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:[distutils] index-servers = pypi [pypi] username:your.pypi.username password:your-password
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.5.0
. -s below makes a signed tag:git tag -s 'Second main release' 0.5.0
Now the version number is OK, push the docs to github pages with:
make upload-html
Set up maintenance / development branches
If this is this is a full release you need to set up two branches, one for further substantial development (often called ‘trunk’) and another for maintenance releases.
Branch to maintenance:
git co -b maint/0.5.x
Set
_version_extra
back to.dev1
and bump_version_micro
by 1. Thus the maintenance series will have version numbers like - say - ‘0.5.1.dev1’ until the next maintenance release - say ‘0.5.1’. Commit. Don’t forget to push upstream with something like:git push upstream maint/0.2.x --set-upstream
Start next development series:
git co main-master
then restore
.dev
to_version_extra
, and bump_version_minor
by 1. Thus the development series (‘trunk’) will have a version number here of ‘0.3.0.dev’ and the next full release will be ‘0.3.0’.Merge
-s ours
the version number changes from the maint release, e.g:git merge -s ours maint/0.3.x
This marks the version number changes commit as merged, so we can merge any changes we need from the maintenance branch without merge conflicts.
If this is just a maintenance release from
maint/0.2.x
or similar, just tag and set the version number to - say -0.2.1.dev
.Push tags:
git push --tags
Announce to the mailing lists.