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

:Authors: David Goodger; Lea Wiemann; open to all Docutils developers
:Contact: goodger@python.org
:Date: $Date: 2009-10-12 09:19:03 +0200 (Mon, 12 Okt 2009) $
:Revision: $Revision: 6176 $
:Copyright: This document has been placed in the public domain.

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


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 a check-in freeze on Docutils-develop.**

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

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

      $ ftp upload.sourceforge.net
      Connected to osdn.dl.sourceforge.net.
      ...
      Name (upload.sourceforge.net:david): anonymous
      331 Anonymous login ok, send your complete e-mail address as password.
      Password:
      ...
      230 Anonymous access granted, restrictions apply.
      ftp> bin
      200 Type set to I.
      ftp> cd /incoming
      250 CWD command successful.
      ftp> put docutils-X.Y.Z.tar.gz

* Access the _`file release system` on SourceForge (Admin
  interface).  

  Not found 2009-10-11 for release 0.6.

  Fill in the fields:

      :Package ID:      docutils
      :Release Name:    <use release number only, e.g. 0.3>
      :Release Date:    <today's date>
      :Status:          Active
      :File Name:       <select the file just uploaded>
      :File Type:       Source .gz
      :Processor Type:  Platform-Independent
      :Release Notes:   <insert README.txt file here>
      :Change Log:      <insert current release notes here>

      Also check the "Preserve my pre-formatted text" box.

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

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

  BUG: not found 2009-10-12.

* **Register with FreshMeat.** (Add a new release for the
  `Docutils project`__).

  __ http://freshmeat.net/projects/docutils/


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