When releasing software, the following steps should be taken:
Make sure all automated tests of the package pass and there are no release-critical bugs in its bug tracker.
Fill in the release date in
CHANGES.rst. Make sure the changelog is complete. Update the version number in
setup.pyand remove the
Also consider the version number for the new release. If the API has been added to, or the behavior has otherwise changed in a way that goes beyond a bugfix, please update the version number for the next release and make it a feature release (x.y) instead of a bugfix release (x.y.z).
Make sure the package metadata in
setup.pyis up-to-date. You can verify the information by re-generating the egg info:
python setup.py egg_info
src/EGGNAME.egg-info/PKG-INFO. You should also make sure the that the long description renders as valid reStructuredText. You can do this by using the
rst2html.pyutility from docutils:
python setup.py --long-description | rst2html.py > test.html
If this will produce warnings or errors, PyPI will be unable to render the long description nicely. It will treat it as plain text instead.
Create a release tag.
Get a separate checkout of the release tag for creating the distribution tarball and eggs. It is important that you don’t do this on the master or release branch to avoid
- forgetting to tag the release at all.
- forgetting to clean up the
builddirectory that distutils and setuptools create. Failure to do so may result in old artefacts in eggs.
- forgetting to check in files that are needed by
setup.pyor as package data. Setuptools will only include them in the distribution if they are specifed by the
In the checkout of the tag create a distribution and upload it to PyPI using the following command:
python setup.py register sdist upload
Back on the master or the release branch, increase the version number in
setup.pyto the next release and add back the
devmarker. The convention is that the master or release branch always points to the upcoming release, not the one that has been released already. So if you’ve just released version 3.4.1, you should change
setup( name='...', version='3.4.2.dev', ... )
CHANGES.rstadd a new section for the upcoming release. The release date for that should say “unreleased” so that committers recording their changes won’t accidentally put their entry in the section for an already released version. For example:
3.4.2 (unreleased) ------------------ * ... 3.4.1 (2007-01-24) ------------------ * Fixed bug in the foo adapter. * Added a bar utility for optimized kaboodling. 3.4.0 (2006-09-13) ------------------ Initial release as separate egg.
Important: Once released to PyPI or any other public download location, a release may never be removed, even if it has proven to be a faulty release (“brown bag release”). In such a case it should simply be superseded immediately by a new, improved release.