Releasing softwareΒΆ

Author:unknow

Steps to take when releasing software.

When releasing software, the following steps should be taken:

  1. Make sure all automated tests of the package pass.

  2. Make sure the package has a LICENSE.txt or similar file. Some distributors like Ubuntu require such a file in sources. See legal stuff for details.

  3. Fill in the release date in CHANGES.txt. Make sure the changelog is complete.

  4. Make sure the package metadata in setup.py is up-to-date. You can verify the information by re-generating the egg info:

    python setup.py egg_info

    and inspecting 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.py utility 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.

  5. Create a release tag.

  6. 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 trunk or release branch to avoid

    1. forgetting to tag the release at all.
    2. forgetting to clean up the build directory that distutils and setuptools create. Failure to do so may result in old artefacts in eggs.
    3. forgetting to check in files that are needed by setup.py or as package data. Setuptools will only include them in the distribution if they are checked into subversion.

    In the checkout of the tag perform the following steps:

    1. Remove the “dev” marker from the version in setup.py

    2. Commit these changes. It’s acceptable that these changes modify the tag since they’re purely related to release management.

    3. Create a distribution and upload it to PyPI using the following command:

      python setup.py register sdist upload

      If the package contains C extensions, you need to upload a binary Windows egg as well:

      python setup.py bdist_egg upload

      This may require the help from someone with a Windows installation and proper tools (Visual C).

      Binary eggs for Linux or MacOSX should never be uploaded because those platforms vary too much to be binary-compatible with each other, due to varying UCS support, different libc versions and linking models (framework / non-framework).

    1. Back on the trunk or the release branch, increase the version number in setup.py to the next release while preserving the dev marker. The convention is that the trunk 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.py to read:

      setup(
    name='...',
    version='3.4.2dev',
    ...
    )

      In CHANGES.txt add 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 released egg 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.