# Docutils Release Procedure

Authors: | David Goodger Lea Wiemann open to all Docutils developers
Contact: | docutils-develop@lists.sourceforge.net
Date: | 2017-08-03
Revision: | 8146
Copyright: | This document has been placed in the public domain.

# 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/ then site-packages is under /usr/local/lib/python2.6.

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.

# Releasing

## Version numbers

Version numbers shall follow the Docutils Project Policies and comply with PEP 440.

Especially, mark pre-releases and the repository version/snapshots as "between" releases (cf. Feature Request #50 and the discussion on docutils-devel on May 28 2017), e.g.

prev. release 0.13.1,
prerelease 0.14rc1,
[prereleases 0.14rc2, ...]
release 0.14,
repo/snapshots 0.15.dev
[bugfix relases 0.14.1, ...] # branches off of the 0.14 release.

The repository version number is always equal to the last released version + 1, with a .dev suffix: `<major>.<minor+1>.dev`. (Exception: during "feature freeze" between pre-release and release it may point to the next pre-release.)

## Release steps

REWORK FOR SOURCEFORGE REPO

Warning

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.

Note

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

Note

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.

  Announce the date of the feature freeze, at least a week away.

  Consult HISTORY.TXT for changes.

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

- Announce the upcoming release at the Sphinx-devel mailing list and ask for testing with Sphinx. (This step can be skipped for bugfix releases.)

- update version numbers:

  We want pre-release tags `rcN` for pre-releases, development release tag `.dev` for snapshots and installs from the repository.

  For a prerelease

  0. before release `<next-release-number>.dev`
  1. set this to `<next-release-number>.rc1`
  2. release
  3. increase prerelease number in the repository

  For a release

  0. before release `<next-release-number>.dev` or `<next-release-number>.rc<N>`
  1. set this to `<next-release-number>` without prerelease character.
  2. release
  3. set to `<major>.<minor+1>.dev` in the repository (trunk).

  see what `sandbox/infrastructure/release.sh` can aid

  Call `sandbox/infrastructure/set_release.sh new_version`. For details see the script.

  `new_version` is major.minor[.micro][<pre>][.dev]

  Note

  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/__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.code.sf.net/p/docutils/code/trunk/docutils

     or via the [Download Snapshot] button at http://sourceforge.net/p/docutils/code/HEAD/tree/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).

     "remove" might fail, see Assumptions and their failure

     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, release.sh tries with scp.

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

  `https://sourceforge.net/projects/docutils/files/docutils/`

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

  Set the download-url so eggs can access older releases.

- 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

- build wheels:

      pip wheel docutils
      pip3 wheel docutils

  This builds wheels (pure Python wheels for Python 2 and 3 respectively) by downloading the new release from pypi.

  Upload the wheels 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?

    2017-06-09 it seems to according to experience with 0.13.1.

- 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"

  Mark as default download for all platforms.

- Register with freecode. Add a new release for the `Docutils project`__. (freecode is freshmeat.net's new name)

# Docutils System Messages

System Message: ERROR/3 (`../docs/dev/release.txt`); backlink

Anonymous hyperlink mismatch: 1 references but 2 targets. See "backrefs" attribute for IDs.