Release Process
This process describes the steps to execute in order to release a new version of mosaik.
Preparations
Make a new release of mosaik-api-python if required. Use this guide as an orientation.
Close all tickets for the next version.
Check all dependencies for new versions and update the exact version of all entries in
requirements.txt
. Update the minium required versions of dependencies insetup.py
if (and only if) necessary.Run tox from the project root. All tests for all supported versions must pass:
$ tox [...] ________ summary ________ py36: commands succeeded py37: commands succeeded congratulations :)
Build the docs (HTML is enough). Make sure there are no errors and undefined references.
$ cd docs/ $ make clean html $ cd ..
Check if all authors are listed in
AUTHORS.txt
.Update the change logs (
CHANGES.txt
anddocs/about/history.rst
). Only keep changes for the current major release inCHANGES.txt
and reference the history page from there.Commit all changes:
$ git commit -m 'Updated change log for the upcoming release.'
Update the version number in
mosaik/_version.py
,setup.py
anddocs/conf.py
and commit:$ git commit -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!
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
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'
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://test.pypi.org/legacy/ username: <your test user name goes here> password: <your test password goes here> [pypi] repository: https://upload.pypi.org/legacy/ username: <your production user name goes here> password: <your production password goes here>
Upload the distributions for the new version to the test server and test the installation again:
$ twine upload -r test dist/mosaik*a.b.c* $ pip install -i https://testpypi.python.org/pypi mosaik
Check if the package is displayed correctly: https://testpypi.python.org/pypi/mosaik
Finally upload the package to PyPI and test its installation one last time:
$ twine upload -r pypi dist/mosaik*a.b.c* $ pip install -U mosaik
Check if the package is displayed correctly: https://pypi.python.org/pypi/mosaik
Post release
Push your changes:
$ git tag a.b.c $ git push ssh://git@gitlab.com/mosaik/mosaik.git
Remove the
build/
directory:$ rm -r build/
Activate the documentation build for the new version.
Make sure, the demo works with the new release.
Send the prepared email to the mailing list.
Create blog post for mosaik.offis.de.