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

:Authors: David Goodger; Lea Wiemann; open to all Docutils developers
:Contact: docutils-develop@lists.sourceforge.net
:Date: $Date: 2016-07-28 09:50:29 +0200 (Do, 28. Jul 2016) $
:Revision: $Revision: 7956 $
: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/ than 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
---------

Note on numbering (Feature Request #50)

  PEP 440 specifies how release version are understood by pip and other tools.

  The last released package of docutils was in 2014.

  If you install the version from Source it will not be overriden by version
  0.13 when it is eventaully released.

  As folks have installed 0.13 from indeterminate source versions the current
  version should be incremented as to allow pip to overrite a 0.13 snapshot
  when the next official release.

  Please increment and switch the version in setup.py to be a pre-release. e.g.
  0.13.1a

  When a version is tagged it should be changed to a non pre release and then
  in the next commit incremented to the next expected version but with a pre
  release added ::

    0.13.1a -> Head
    0.13.1 -> when tagged for release
    0.13.2a -> new head after release

  Additionally snapshots can be marked with the .devXXX nominclature.

These can then all be pushed to pypi.python.org and by default pip will install the latest release unless explicitly requested via the --pre flag or a version specifier docutils>=0.13.1a

REWORK FOR SOURCEFORGE REPO

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

  Consult HISTORY.TXT for changes.

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

Call ``sandbox/infrastructure/release.sh 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.

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

  .. note:: PyPI recommends to `create and upload wheels`_ in addition to
            the source tarball.

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

  _`create and upload wheels`:

* The `Python Packaging User Guide` recommends to provide `wheels`_ [#]_ 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__.

  .. _wheels: https://packaging.python.org/en/latest/distributing.html#wheels
  __ https://pypi.python.org/pypi/pip/

  See also `feature request 43
  <https://sourceforge.net/p/docutils/feature-requests/43/>`__

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

  __ https://packaging.python.org/en/latest/distributing.html#pure-python-wheels


  + Eventually install the `pip <https://pypi.python.org/pypi/pip/>`__` and
    `wheel <https://pypi.python.org/pypi/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`__

  __ https://packaging.python.org/en/latest/distributing.html#upload-your-distributions


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

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

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

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