Wendelin.core - Release Howto Author: Kirill Smelkov <firstname.lastname@example.org> Date: 2015 June 16 last-updated-for: wendelin.core v0.3 Abstract This document describes steps needed to make a new release of wendelin.core Make worktree clean Either make sure your working tree is clean: $ git clean -fdX $ git submodule foreach git clean -fdX or clone wendelin.core afresh: $ git clone --recursive https://lab.nexedi.com/nexedi/wendelin.core $ cd wendelin.core Increase version & describe changes Increment version in setup.py . Describe what has been changed in this release in CHANGES. Make sure it works Run set-up tox tests. This will test whether wendelin.core builds ok with various python versions and various ZODB versions: $ tox tail of output should be something like: ... ________ summary ________ py27-ZODB3: commands succeeded py27-ZODB4: commands succeeded py34-ZODB4: commands succeeded congratulations :) Note if you experience failures, while running tox, e.g. code crashes saying zodbpickle module is not found, before running tests, make sure your tox/virtualenv is uptodate. e.g. on Debian system: $ virtualenv venv-4release $ . venv-4release/bin/activate $ pip install tox $ hash -r Make release commit Ensure to stage changes in setup.py and CHANGES for commit. E.g. with: $ git add -p ( interactively select changes to commit ) Ensure all changes were staged and there will be no other changes in worktree after commit: $ git status ( should be absent or empty section "Changes not staged for commit:" ) Make release commit: $ git commit -S -m "wendelin.core vX.y" Make release tag: $ git tag -s -m "wendelin.core vX.y" vX.y Note The commit and tag are made gpg-signed (the -S and -s options) Prepare release tarball $ python setup.py sdist this should create dist/wendelin.core-X.y.tar.gz . Check restructured text syntax $ twine check dist/* this checks that the syntax of the long description is written in a syntaxically correct restructured text and will render properly on pypi. It's also a good idea to use a spellchecker to detect English mistakes. Test release tarball Unpack intended-to-release tarball somewhere and test it again with tox: $ mkdir tmp $ cd tmp $ tar xfz ../dist/wendelin.core-X.y.tar.gz $ cd wendelin.core-X.y $ tox The output should be again: ... ________ summary ________ py27-ZODB3: commands succeeded py27-ZODB4: commands succeeded py34-ZODB4: commands succeeded congratulations :) Warning If not: investigate what is wrong / what needs to be corrected. remove release tag and commit: $ git tag -d vX.y $ git reset HEAD~ # keeping made changes to setup.py & CHANGES fix problems; go again to Make release commit. Sign release tarball If release tarball was tested ok - sign it: $ gpg --armor --detach-sign wendelin.core-X.y.tar.gz Upload to PyPI After release tarball is ready and signed - upload it to PyPI: $ twine upload -u <your-pypi-account> wendelin.core-X.y.tar.gz* Warning Do not use PyPI web UI to upload new release. The UI has bugs which will prevent uploading this release further even with twine or setup.py upload. after uploading, make sure that sha512sum shown on PyPI corresponds to real sha512sum of dist/wendelin.core-X.y.tar.gz . PGP signature shown on PyPI is the same as dist/wendelin.core-X.y.tar.gz.asc . Note that currently PyPI does not directly display the signature in the web interface, but it's possible to download the .asc by appending .asc to the tarball download URL . Push release commit & tag to public git repo $ git push origin master vX.y Make release announcement (optional for now) Tell the world - send email about new release to corresponding mailing lists, LWN.net, etc . Make announcements on twitter and facebook.