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.

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

• 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)