Docutils Release Procedure

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

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

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

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

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

  • docutils/setup.py
  • docutils/docutils/__init__.py
  • 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://svn.berlios.de/docutils/trunk/docutils
     

  3. Use Distutils to create the release tarball:

     cd docutils
     python setup.py sdist
     

• 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 roman.py, and optparse.py, textwrap.py).

     Install from expanded directory:

     cd docutils-X.Y.Z
     python setup.py 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 alltests.py
  

• 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/
  ./buildhtml.py ..
  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>@shell.sourceforge.net:
  

  Now log in to shell.sourceforge.net 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:

  $ ftp upload.sourceforge.net
  Connected to osdn.dl.sourceforge.net.
  ...
  Name (upload.sourceforge.net:david): anonymous
  331 Anonymous login ok, send your complete e-mail address as password.
  Password:
  ...
  230 Anonymous access granted, restrictions apply.
  ftp> bin
  200 Type set to I.
  ftp> cd /incoming
  250 CWD command successful.
  ftp> put docutils-X.Y.Z.tar.gz
  

• Access the file release system on SourceForge (Admin interface). Fill in the fields:

  Package ID:	docutils
  Release Name:	<use release number only, e.g. 0.3>
  Release Date:	<today's date>
  Status:	Active
  File Name:	<select the file just uploaded>
  File Type:	Source .gz
  Processor Type:	Platform-Independent
  Release Notes:	<insert README.txt file here>
  Change Log:	<insert current release notes here>

  Also check the "Preserve my pre-formatted text" box.

• 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 setup.py register).

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

• 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 alltests.py with svn version

• Send announcement email to:

  • docutils-develop@lists.sourceforge.net (also announcing the end of the check-in freeze)
  • docutils-users@lists.sourceforge.net
  • doc-sig@python.org
  • python-announce@python.org

• Add a SourceForge News item, with title "Docutils X.Y.Z released" and containing the release tarball's download URL.

• Register with FreshMeat. (Add a new release for the Docutils project).