Release Process — mosaik 2.0a1 documentation

# Release Process

This process describes the steps to execute in order to release a new version of mosaik.

## Preparations

1. Make a new release of mosaik-api-python if required. Use this guide as an orientation.

2. Close all tickets for the next version.

3. Update the minium required versions of dependencies in `setup.py`. Update the exact version of all entries in `requirements.txt`.

4. Run tox from the project root. All tests for all supported versions must pass:

       $ tox
       [...]
       ________ summary ________
       py33: commands succeeded
       py34: commands succeeded
       congratulations :)

5. Build the docs (HTML is enough). Make sure there are no errors and undefined references.

       $ cd docs/
       $ make clean html
       $ cd ..

6. Check if all authors are listed in `AUTHORS.txt`.

7. Update the change logs (`CHANGES.txt` and `docs/about/history.rst`). Only keep changes for the current major release in `CHANGES.txt` and reference the history page from there.

8. Commit all changes:

       $ hg ci -m 'Updated change log for the upcoming release.'

9. Update the version number in `mosaik/__init__.py`, `setup.py` and `docs/conf.py`. Commit and create a tag:

       $ hg ci -m 'Bump version from x.y.z to a.b.c'

   Warning

   Do not yet tag and push the changes so that you can safely do a rollback if one of the next step fails and you need change something!

10. Write a draft for the announcement mail with a list of changes, acknowledgements and installation instructions. Everyone in the team should agree with it.

## Build and release

1. Test the release process. Build a source distribution and a wheel package and test them:

       $ python setup.py sdist bdist_wheel
       $ ls dist/
       mosaik-a.b.c-py2.py3-none-any.whl mosaik-a.b.c.tar.gz

   Try installing them:

       $ rm -rf /tmp/mosaik-sdist  # ensure clean state if ran repeatedly
       $ virtualenv -p /usr/bin/python3 /tmp/mosaik-sdist
       $ /tmp/mosaik-sdist/bin/pip install dist/mosaik-a.b.c.tar.gz
       $ /tmp/mosaik-sdist/bin/python
       >>> import mosaik  # doctest: +SKIP
       >>> mosaik.__version__  # doctest: +SKIP
       'a.b.c'

   and

       $ rm -rf /tmp/mosaik-wheel  # ensure clean state if ran repeatedly
       $ virtualenv -p /usr/bin/python3 /tmp/mosaik-wheel
       $ /tmp/mosaik-wheel/bin/pip install dist/mosaik-a.b.c-py2.py3-none-any.whl
       $ /tmp/mosaik-wheel/bin/python
       >>> import mosaik  # doctest: +SKIP
       >>> mosaik.__version__  # doctest: +SKIP
       'a.b.c'

2. Create or check your accounts for the test server and PyPI. Update your `~/.pypirc` with your current credentials:

       [distutils]
       index-servers =
           pypi
           test

       [test]
       repository = https://testpypi.python.org/pypi
       username = <your test user name goes here>
       password = <your test password goes here>

       [pypi]
       repository = http://pypi.python.org/pypi
       username = <your production user name goes here>
       password = <your production password goes here>

3. Upload the distributions for the new version to the test server:

       $ twine upload -r test dist/mosaik*a.b.c*

4. Check if the package is displayed correctly: https://testpypi.python.org/pypi/mosaik

5. Test the installation again:

       $ pip install -i https://testpypi.python.org/pypi mosaik

6. Finally upload the package to PyPI and test its installation one last time:

       $ twine upload -r pypi dist/mosaik*a.b.c*

7. Check if the package is displayed correctly: https://pypi.python.org/pypi/mosaik

8. Activate the documentation build for the new version.

## Post release

1. Push your changes:

       $ hg tag a.b.c
       $ hg push ssh://hg@bitbucket.org/mosaik/mosaik

2. Send the prepared email to the mailing list.

3. Create blog post for mosaik.offis.de.