Preparing a release¶

Rules for a release branch:

May branch from: develop

Must be merged into: master (and develop if needed)

Naming convention: release-* where * 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 develop via the developer mailing list
Create a release branch from develop:
```
git checkout -b release-0.7.6 develop
```
Finalise the CHANGELOG with the release number and date. Summarize important changes and add all authors that contributed to this release.
Make sure the version number is right:
```
./maintainer/change_release.sh 0.7.6
```
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 package/dist/MDAnalysis-MAJOR-MINOR-PATCH.tar.gz and testsuite/dist/MDAnalysisTests-MAJOR-MINOR-PATCH.tar.gz:
# MDAnalysis cd package/ python setup.py sdist # MDAnalysisTests cd ../testsuite/ python setup.py sdist

Test the distribution in a tmp directory.

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)
1. Upload the package to Pypi. You need to have run python setup.py register previously.
  twine upload -r pypi dist/MDAnalysis-0.16.2.tar.gz
2. Upload the docs to Pypi
3. Make the new tar ball a featured release so that it shows up on the front page (and unfeature any older releases).
4. Provide a short description (a condensed version of the CHANGELOG)
Update the release on Anaconda
conda packages are built on conda-forge.
1. Create a pull request from https://github.com/MDAnalysis/mdanalysis-feedstock for https://github.com/conda-forge/mdanalysis-feedstock
2. 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 CHANGELOG as a reference). Add it to the Release Notes.
Delete the release branch:
```
git branch -d release-0.7.6
```