Preparing a release¶
Rules for a release branch:
May branch from:
Must be merged into:
*is a version number
Release policy and release numbering¶
We use a MAJOR.MINOR.PATCH scheme to label releases. We adhere to the idea of semantic versioning (semantic versioning was introduced with release 0.9, see Issue 200): Given a version number MAJOR.MINOR.PATCH, we increment the:
MAJOR version when we make incompatible API changes,
MINOR version when we add functionality in a backwards-compatible manner, and
PATCH version when we make backwards-compatible bug fixes.
However, as long as the MAJOR number is 0 (i.e. the API has not stabilized), even MINOR increases may introduce incompatible API changes. As soon as we have a 1.0.0 release, the public API can only be changed in a backward-incompatible manner with an increase in MAJOR version.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
The CHANGELOG lists important changes for each release.
MAJOR, MINOR and PATCH numbers are integers that increase monotonically.
The release number is set in setup.py and in
MDAnalysis.__version__ (MDAnalysis/version.py), e.g.
RELEASE = '0.7.5'
While the code is in development (i.e. whenever we are not preparing a release!) the release number gets the suffix -dev0, e.g.
RELEASE = '0.7.6-dev0'
so that people using the develop branch from the source repository can immediately see that it is not a final release. For example, “0.7.6-dev0” is the state before the 0.7.6 release.
Typical workflow for preparing a release¶
Declare feature freeze on
developvia the developer mailing list
Create a release branch from
git checkout -b release-0.7.6 develop
CHANGELOGwith the release number and date. Summarize important changes and add all authors that contributed to this release.
Make sure the version number is right:
Check that the documentation is up-to-date and tests pass. Check that any new Cython code has compiled.
Commit the finalized state:
git commit -m "release 0.7.6 ready"
Build a source distribution tarballs under
# MDAnalysis cd package/ python setup.py sdist # MDAnalysisTests cd ../testsuite/ python setup.py sdist
Test the distribution in a
Unpack and try to build it:
mkdir tmp && cd tmp tar -zxvf ../dist/MDAnalysis-0.7.5.tar.gz cd MDAnalysis-0.7.5 python setup.py build --build-lib=.
Run the tests again:
python >>> import MDAnalysis.tests >>> MDAnalysis.tests.test(label='full', extra_argv=['--exe'])
The above should work at least on Linux and Mac OS X. If it fails then go back and fix things and do not release.
If everything works, merge the branch into master and tag the release:
git checkout master git merge --no-ff release-0.7.6 git tag -m 'release 0.7.5 of MDAnalysis and MDAnalysisTests' release-0.7.5 git push --tags origin master
Merge the branch back into
develop(this is not required if the only change was the version number):
git checkout develop git merge --no-ff release-0.7.6 ./maintainer/change_release.sh 0.7.7-devel git commit -a -m "version number changed to 0.7.7-devel"
Build and deploy the docs manually. (You may need to first
pip install sphinx==2.2.0 sphinx_sitemap sphinx_rtd_theme):
cd package/ python setup.py build_sphinx cd .. # You need a OAUTH token that gives commit access to the MDAnalysis/docs repo export GH_TOKEN=<secret> ./maintainer/deploy_master_docs.sh
Update the release on the Python package index (Pypi)
Upload the package to Pypi. You need to have run
python setup.py registerpreviously.
twine upload -r pypi dist/MDAnalysis-0.16.2.tar.gz
Upload the docs to Pypi
Make the new tar ball a featured release so that it shows up on the front page (and unfeature any older releases).
Provide a short description (a condensed version of the
Update the release on Anaconda
conda packages are built on conda-forge.
Create a pull request from https://github.com/MDAnalysis/mdanalysis-feedstock for https://github.com/conda-forge/mdanalysis-feedstock
Create a pull request from https://github.com/MDAnalysis/mdanalysistests-feedstock to https://github.com/conda-forge/mdanalysistests-feedstock
Create a ReleaseXYZ wiki page, modelled after e.g. Release062 (using the
CHANGELOGas a reference). Add it to the Release Notes.
Delete the release branch:
git branch -d release-0.7.6