Making Nengo releases¶

While we endeavour to automate as much as the below as possible, it’s nonetheless important to know how a Nengo release works. There are three stages to this process, which will result in at least two git commits and one git tag.

Note that these steps should be consulted for both release candidates, and full releases. However, some steps (notably those that interact with PyPI) should be omitted for release candidates.

Stage 1: Preparation¶

Before making a release, we do a few things to prepare:

Ensure master is up-to-date by doing git pull.
Ensure that important changes since the last release are chronicled in the changelog (CHANGES.rst).
Run check-manifest to ensure that all files are included in the release.
Run all unit test to ensure they pass on all supported versions. This includes tests that are normally skipped due to slow runtimes. This requires that optional dependencies are installed. Currently, running all tests is done with NENGO_TEST_PLOT=1 pytest --pyargs nengo --benchmarks --optional (in environments for each supported Python).
Review all of the plots generated from running the unit tests for abnormalities or unclear figures.
Build the documentation and review all of the rendered examples for abnormalities or unclear figures.
Commit all changes from above before moving on to stage 2.

Todo

Step 4 is a bit vague at the moment; we should have a separate document for all the platforms supported, and how to test on Windows with Vagrant, etc. However, it is also the hope that release candidates will be tested by many different environments reducing the burden on the developers to have all possible environments available.

Note that any possibly controversial fixes done as a result of Stage 1 should be done through the normal process of making a pull request and going through review. However, from Stage 2 onward, the work is done directly on the master branch. It can therefore result in bad things, so proceed with caution!

Stage 2: Make release commit¶

Once everything is prepared, we’re ready to do the release. It should be okay to work in the same directory that you do development, but if you want to be extra safe, you can do a fresh clone of Nengo into a separate directory.

Change the version information in nengo/version.py. See that file for details.
If this is a release, set the release date in the changelog (CHANGES.rst).
git add the changes above and make a release commit with: git commit -m "Release version $(python -c 'import nengo; print(nengo.__version__)')"
Review git log to ensure that the version number is correct; if not, then something went wrong with the previous steps. Correct these mistakes and amend the release commit accordingly.
Tag the release commit with the version number; i.e., git tag -a v$(python -c 'import nengo; print(nengo.__version__)'). We use annotated tags for the authorship information; if you wish to provide a message with information about the release, feel free, but it is not necessary.
git push origin master and git push origin [tagname].
If this is a release, create a package and upload it to PyPI with python setup.py sdist upload.
If this is a release, build the documentation with python setup.py build_sphinx. Zip it up and upload it through this form

Stage 3: Post-release cleanup¶

Nengo’s now released! We need to do a few last things to put Nengo back in a development state.

Change the version information in nengo/version.py. See that file for details.
If this is a release, make a new changelog entry in CHANGES.rst in order to collect changes for the next release.
git add the changes above and make a commit describing the current state of the repository; either git commit -m "Continuing development of vX.Y.Z" or git commit -m "Starting development of vX.Y.Z".
git push origin master

Congrats, you’ve released Nengo! Shake off the nerves of working directly on master, and make sure that pip install nengo gets the new version, if it was a full release.