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

:Authors: David Goodger; Lea Wiemann; open to all Docutils developers
:Contact: docutils-develop@lists.sourceforge.net
:Date: $Date: 2013-07-13 20:14:43 +0200 (Sam, 13. Jul 2013) $
:Revision: $Revision: 7686 $
: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 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
---------

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.berlios.de/docutils/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**
    
* **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/


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