Docutils Release Procedure

Authors:David Goodger; Lea Wiemann; open to all Docutils developers
Date:$Date: 2015-05-08 15:56:32 +0000 (Fri, 08 May 2015) $
Revision:$Revision: 7889 $

このドキュメントは、パブリック ドメインで公開されています。

Assumptions and their failure

On the test machine python2.4, 2.5, 2.6, 2.7 and 3.2, 3.3, and 3.4 are installed. Some in /usr/ some under /usr/local.

Assumption: If python2.6 is in /usr/bin/ than site-packages is under

On new ubuntu 12.10

  • python2.7 is here /usr/bin/python2.7.

  • in /usr/lib are python2.7, pymodules and pyshared.

    in /usr/lib/python2.7 no site-packages directory even after installation of docutils

    in /usr/local/lib/python2.7 are dist-packages site-packages.

    site-packages is empty.

    docutils is installed under dist-packages.

    pymodules has a python2.7 directory.



Steps in boldface text are not covered by the release script at sandbox/infrastructure/ "Not covered" means that you aren't even reminded of them.


This document does not cover branching and tagging, but the release script does.


You may want to use ReleaseForge instead of using SourceForge's file release system.

  • On the Docutils-develop mailing list, announce that the release is going to be made, update the release notes and ask for additions.

    Consult HISTORY.TXT for changes.

  • Announce a check-in freeze on Docutils-develop.

Call sandbox/infrastructure/ new_version svn_version. For details see the script.

new_version is the current version, status will change from repository to release. svn_version is the version after release.


BUG test tarball requires root password, but it is possible to skip this stage interactively, and testing should be done before release.

  • Change __version_details__ in docutils/docutils/ to "release" (from "repository").

  • Check the version number in the following files, should be already correct:

    • docutils/
    • docutils/docutils/
    • docutils/test/functional/expected/* ("Generator: Docutils X.Y.Z")
    • docutils/README.txt
    • web/index.txt
  • Close the "Changes Since ..." section in docutils/HISTORY.txt.

  • Clear/unset the PYTHONPATH environment variable.

  • Create the release tarball:

    1. Create a new empty directory and cd into it.

    2. Get a clean snapshot of the main tree:

      svn export svn://

      or via the [Download Snapshot] button at

    3. Use Distutils to create the release tarball:

      cd docutils
      python sdist


    PyPI recommends to create and upload wheels in addition to the source tarball.

  • Expand and install the release tarball in isolation:

    1. Expand the tarball in a new location, not over any existing files.

    2. Remove the old installation from site-packages (including, and,

      "remove" might fail, see Assumptions and their failure

      Install from expanded directory:

      cd docutils-X.Y.Z
      python install

      The "install" command may require root permissions.

    3. Repeat step b) for all supported Python versions.

  • Run the test suite from the expanded archive directory with all supported Python versions on all available platforms (GNU/Linux, Mac OS X, Windows):

    cd test ; python -u
  • Add a directory X.Y.Z (where X.Y.Z is the current version number of Docutils) in the webroot (i.e. the htdocs/ directory). Put all documentation files into it:

    cd docutils-X.Y.Z
    rm -rf build
    cd tools/
    ./ ..
    cd ..
    find -name test -type d -prune -o -name \*.css -print0 \
        -o -name \*.html -print0 -o -name \*.txt -print0 \
        | tar -cjvf docutils-docs.tar.bz2 -T - --null
    scp docutils-docs.tar.bz2 <username>

    Now log in to and:

    cd /home/groups/d/do/docutils/htdocs/
    mkdir -m g+rwxs X.Y.Z
    cd X.Y.Z
    tar -xjvf ~/docutils-docs.tar.bz2
    rm ~/docutils-docs.tar.bz2
  • Upload the release tarball, tries with scp.

  • Access the file release system on SourceForge (Admin interface).

    • change into the released version's directory
    • click (i) button of the tar.gz-file
    • select as default download for all operating systems.
  • Submit a notification on project news.

  • For verifying the integrity of the release, download the release tarball (you may need to wait up to 30 minutes), install it, and re-run the test suite.

  • Register with PyPI (python register).

    Restore __version_details__ in docutils/docutils/ to "repository" (from "release").

    create and upload wheels:

  • The Python Packaging User Guide recommends to provide wheels [1] in addition to the source tarball.


    A Built Distribution format introduced by pypa:PEP427s, which is intended to replace the Egg format. Wheel is currently supported by pip.

    See also feature request 43

    For current Docutils, this would mean pure Python wheels for Python 2 and 3 respectively.

    • Eventually install the pip <>`__ and wheel packages.

    • Produce wheels:

      For the default Python version:

      • From release at PyPI

        pip wheel docutils
      • From working directory's sub-directory "docutils"

        pip wheel ./docutils/

      Under Debian, the default Python version is 2.7 and the wheel is usable for all 2.x versions supported by Docutils and the command pip3 wheel docutils generates a wheel suitable for Py3k.

    • Upload to PyPI

  • Bump the version number again.

  • Add a new empty section "Changes Since ..." in HISTORY.txt.

  • Update the web page (web/index.txt).

  • Run docutils-update on the server.

  • Run with svn version

  • Send announcement email to:

  • (also announcing the end of the check-in freeze)

  • BUG: not found 2009-10-12.

    Mark as default download for all platforms.

  • Register with freecode. Add a new release for the Docutils project. (freecode is's new name)

  • build a wheel at least for python3:

    pip3 wheel docutils

    This builds the wheel by downloading the new release from pypi.

    Upload the wheel to pypi.

    Question: Can we have an tar.gz (distutil) and a py2-wheel and a py3-wheel

    on pypi and will installers select the correct files ?