.. -*- coding: utf-8 -*-
.. _preparing-release:
===================
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 :ref:`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.
.. _`Issue 200`: https://github.com/MDAnalysis/mdanalysis/issues/200
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``:
.. code-block:: bash
# 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:
.. code-block:: bash
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:
.. code-block::
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=
./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 register`` previously.
.. code-block:: bash
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 ``CHANGELOG``)
#. 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 ``CHANGELOG`` as a reference). Add it to the `Release Notes `_.
#. Delete the release branch::
git branch -d release-0.7.6
.. _`developer mailing list`: https://groups.google.com/forum/#!forum/mdnalysis-devel