=============================
 Docutils_ Release Procedure
=============================

:Authors: David Goodger; Lea Wiemann; open to all Docutils developers
:Contact: docutils-develop@lists.sourceforge.net
:Date: $Date: 2017-08-03 11:00:21 +0200 (Do, 03 Aug 2017) $
:Revision: $Revision: 8146 $
:Copyright: This document has been placed in the public domain.

.. _Docutils: http://docutils.sourceforge.net/

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

.. _Docutils Project Policies: policies.html#version-numbers
.. _Feature Request #50: https://sourceforge.net/p/docutils/feature-requests/50/
.. _PEP 440: https://www.python.org/dev/peps/pep-0440/

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.

   .. _ReleaseForge: http://releaseforge.sourceforge.net/


* **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:

  (a) Create a new empty directory and ``cd`` into it.

  (b) 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/

  (c) Use Distutils to create the release tarball::

          cd docutils
          python setup.py sdist

* Expand and _`install` the release tarball in isolation:

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

  (b) 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.

  (c) 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.

  .. _wheels: https://packaging.python.org/en/latest/distributing.html#wheels
  .. _pure Python wheels:
     https://packaging.python.org/en/latest/distributing.html#pure-python-wheels
  .. _Upload the wheels to PyPI:
     https://packaging.python.org/en/latest/distributing.html#upload-your-distributions

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

  __ https://sourceforge.net/p/docutils/news

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

  __ http://freecode.com/projects/docutils/


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: