docs/dev/release.txt

   1 =============================
   2  Docutils_ Release Procedure
   3 =============================
   4
   5 :Authors: David Goodger; Lea Wiemann; open to all Docutils developers
   6 :Contact: goodger@python.org
   7 :Date: $Date$
   8 :Revision: $Revision$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. _Docutils: http://docutils.sourceforge.net/
  12
  13
  14 Steps in boldface text are *not* covered by the release script at
  15 sandbox/infrastructure/release.sh.  "Not covered" means that you aren't even
  16 reminded of them.
  17
  18 .. Note:: This document does not cover branching and tagging, but the
  19    release script does.
  20
  21 .. Note:: You may want to use ReleaseForge_ instead of using
  22    SourceForge's file release system.
  23
  24    .. _ReleaseForge: http://releaseforge.sourceforge.net/
  25
  26
  27 * **On the Docutils-develop mailing list, announce that the release is
  28   going to be made, update the release notes and ask for additions.**
  29
  30 * **Announce a check-in freeze on Docutils-develop.**
  31
  32 * Change ``__version_details__`` in docutils/docutils/__init__.py to
  33   "release" (from "repository").
  34
  35 * Bump the _`version number` in the following files:
  36
  37   + docutils/setup.py
  38   + docutils/docutils/__init__.py
  39   + docutils/test/functional/expected/* ("Generator: Docutils X.Y.Z")
  40
  41 * Close the "Changes Since ..." section in docutils/HISTORY.txt.
  42
  43 * Clear/unset the PYTHONPATH environment variable.
  44
  45 * Create the release tarball:
  46
  47   (a) Create a new empty directory and ``cd`` into it.
  48
  49   (b) Get a clean snapshot of the main tree::
  50
  51           svn export svn://svn.berlios.de/docutils/trunk/docutils
  52
  53   (c) Use Distutils to create the release tarball::
  54
  55           cd docutils
  56           python setup.py sdist
  57
  58 * Expand and _`install` the release tarball in isolation:
  59
  60   (a) Expand the tarball in a new location, not over any existing
  61       files.
  62
  63   (b) Remove the old installation from site-packages (including
  64       roman.py, and optparse.py, textwrap.py).
  65
  66       Install from expanded directory::
  67
  68           cd docutils-X.Y.Z
  69           python setup.py install
  70
  71       The "install" command may require root permissions.
  72
  73   (c) Repeat step b) for all supported Python versions.
  74
  75 * Run the _`test suite` from the expanded archive directory with all
  76   supported Python versions on all available platforms (GNU/Linux, Mac
  77   OS X, Windows)::
  78
  79       cd test ; python -u alltests.py
  80
  81 * Add a directory X.Y.Z (where X.Y.Z is the current version number
  82   of Docutils) in the webroot (i.e. the ``htdocs/`` directory).
  83   Put all documentation files into it::
  84
  85       cd docutils-X.Y.Z
  86       rm -rf build
  87       cd tools/
  88       ./buildhtml.py ..
  89       cd ..
  90       find -name test -type d -prune -o -name \*.css -print0 \
  91           -o -name \*.html -print0 -o -name \*.txt -print0 \
  92           | tar -cjvf docutils-docs.tar.bz2 -T - --null
  93       scp docutils-docs.tar.bz2 <username>@shell.sourceforge.net:
  94
  95   Now log in to shell.sourceforge.net and::
  96
  97       cd /home/groups/d/do/docutils/htdocs/
  98       mkdir -m g+rwxs X.Y.Z
  99       cd X.Y.Z
 100       tar -xjvf ~/docutils-docs.tar.bz2
 101       rm ~/docutils-docs.tar.bz2
 102
 103 * Upload the release tarball::
 104
 105       $ ftp upload.sourceforge.net
 106       Connected to osdn.dl.sourceforge.net.
 107       ...
 108       Name (upload.sourceforge.net:david): anonymous
 109       331 Anonymous login ok, send your complete e-mail address as password.
 110       Password:
 111       ...
 112       230 Anonymous access granted, restrictions apply.
 113       ftp> bin
 114       200 Type set to I.
 115       ftp> cd /incoming
 116       250 CWD command successful.
 117       ftp> put docutils-X.Y.Z.tar.gz
 118
 119 * Access the _`file release system` on SourceForge (Admin
 120   interface).  Fill in the fields:
 121
 122       :Package ID:      docutils
 123       :Release Name:    <use release number only, e.g. 0.3>
 124       :Release Date:    <today's date>
 125       :Status:          Active
 126       :File Name:       <select the file just uploaded>
 127       :File Type:       Source .gz
 128       :Processor Type:  Platform-Independent
 129       :Release Notes:   <insert README.txt file here>
 130       :Change Log:      <insert current release notes here>
 131
 132       Also check the "Preserve my pre-formatted text" box.
 133
 134 * For verifying the integrity of the release, download the release
 135   tarball (you may need to wait up to 30 minutes), install_ it, and
 136   re-run the `test suite`_.
 137
 138 * Register with PyPI (``python setup.py register``).
 139
 140 * Restore ``__version_details__`` in docutils/docutils/__init__.py to
 141   "repository" (from "release").
 142
 143 * Bump the `version number`_ again.
 144
 145 * Add a new empty section "Changes Since ..." in HISTORY.txt.
 146
 147 * Update the web page (web/index.txt).
 148
 149 * Run docutils-update on the server.
 150
 151 * **Send announcement email to:**
 152
 153   * docutils-develop@lists.sourceforge.net (also announcing the end of
 154     the check-in freeze)
 155   * docutils-users@lists.sourceforge.net
 156   * doc-sig@python.org
 157   * python-announce@python.org
 158
 159 * **Add a SourceForge News item, with title "Docutils X.Y.Z released"
 160   and containing the release tarball's download URL.**
 161
 162 * **Register with FreshMeat.** (Add a `new release`__ for the
 163   `Docutils project`__).
 164
 165   __ http://freshmeat.net/add-release/48702/
 166   __ http://freshmeat.net/projects/docutils/
 167
 168
 169 \f
 170 ..
 171    Local Variables:
 172    mode: indented-text
 173    indent-tabs-mode: nil
 174    sentence-end-double-space: t
 175    fill-column: 70
 176    End: