docs/dev/release.txt

   1 =============================
   2  Docutils_ Release Procedure
   3 =============================
   4
   5 :Authors: David Goodger; Lea Wiemann; open to all Docutils developers
   6 :Contact: docutils-develop@lists.sourceforge.net
   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 Assumptions and their failure
  14 -----------------------------
  15
  16 On the test machine python2.4, 2.5, 2.6, 2.7 and 3.2, 3.3, and 3.4
  17 are installed.
  18 Some in /usr/ some under /usr/local.
  19
  20 Assumption: If python2.6 is in /usr/bin/ than site-packages is under
  21   /usr/local/lib/python2.6.
  22
  23 On new ubuntu 12.10
  24
  25 * python2.7 is here /usr/bin/python2.7.
  26 * in /usr/lib are python2.7, pymodules and pyshared.
  27
  28   in /usr/lib/python2.7 no site-packages directory even after installation
  29   of docutils
  30
  31   in /usr/local/lib/python2.7 are dist-packages  site-packages.
  32
  33   site-packages is empty.
  34
  35   docutils is installed under dist-packages.
  36
  37   pymodules has a python2.7 directory.
  38
  39 Releasing
  40 ---------
  41
  42 REWORK FOR SOURCEFORGE REPO
  43
  44 Steps in boldface text are *not* covered by the release script at
  45 sandbox/infrastructure/release.sh.  "Not covered" means that you aren't even
  46 reminded of them.
  47
  48 .. Note:: This document does not cover branching and tagging, but the
  49    release script does.
  50
  51 .. Note:: You may want to use ReleaseForge_ instead of using
  52    SourceForge's file release system.
  53
  54    .. _ReleaseForge: http://releaseforge.sourceforge.net/
  55
  56
  57 * **On the Docutils-develop mailing list, announce that the release is
  58   going to be made, update the release notes and ask for additions.**
  59
  60   Consult HISTORY.TXT for changes.
  61
  62 * **Announce a check-in freeze on Docutils-develop.**
  63
  64 Call ``sandbox/infrastructure/release.sh new_version svn_version``.
  65 For details see the script.
  66
  67 ``new_version`` is the current version, status will change from ``repository`` to
  68 ``release``. ``svn_version`` is the version after release.
  69
  70 .. Note:: *BUG* test tarball requires root password, but it is possible to skip
  71    this stage interactively, and testing should be done before release.
  72
  73 * Change ``__version_details__`` in docutils/docutils/__init__.py to
  74   "release" (from "repository").
  75
  76 * Check the _`version number` in the following files, should be already
  77   correct:
  78
  79   + docutils/setup.py
  80   + docutils/docutils/__init__.py
  81   + docutils/test/functional/expected/* ("Generator: Docutils X.Y.Z")
  82   + docutils/README.txt
  83   + web/index.txt
  84
  85 * Close the "Changes Since ..." section in docutils/HISTORY.txt.
  86
  87 * Clear/unset the PYTHONPATH environment variable.
  88
  89 * Create the release tarball:
  90
  91   (a) Create a new empty directory and ``cd`` into it.
  92
  93   (b) Get a clean snapshot of the main tree::
  94
  95           svn export svn://svn.code.sf.net/p/docutils/code/trunk/docutils
  96
  97       or via the [Download Snapshot] button at
  98       http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
  99
 100   (c) Use Distutils to create the release tarball::
 101
 102           cd docutils
 103           python setup.py sdist
 104
 105   .. note:: PyPI recommends to `create and upload wheels`_ in addition to
 106             the source tarball.
 107
 108 * Expand and _`install` the release tarball in isolation:
 109
 110   (a) Expand the tarball in a new location, not over any existing
 111       files.
 112
 113   (b) Remove the old installation from site-packages (including
 114       roman.py, and optparse.py, textwrap.py).
 115
 116       "remove" might fail, see _`Assumptions and their failure`
 117
 118       Install from expanded directory::
 119
 120           cd docutils-X.Y.Z
 121           python setup.py install
 122
 123       The "install" command may require root permissions.
 124
 125   (c) Repeat step b) for all supported Python versions.
 126
 127 * Run the _`test suite` from the expanded archive directory with all
 128   supported Python versions on all available platforms (GNU/Linux, Mac
 129   OS X, Windows)::
 130
 131       cd test ; python -u alltests.py
 132
 133 * Add a directory X.Y.Z (where X.Y.Z is the current version number
 134   of Docutils) in the webroot (i.e. the ``htdocs/`` directory).
 135   Put all documentation files into it::
 136
 137       cd docutils-X.Y.Z
 138       rm -rf build
 139       cd tools/
 140       ./buildhtml.py ..
 141       cd ..
 142       find -name test -type d -prune -o -name \*.css -print0 \
 143           -o -name \*.html -print0 -o -name \*.txt -print0 \
 144           | tar -cjvf docutils-docs.tar.bz2 -T - --null
 145       scp docutils-docs.tar.bz2 <username>@shell.sourceforge.net:
 146
 147   Now log in to shell.sourceforge.net and::
 148
 149       cd /home/groups/d/do/docutils/htdocs/
 150       mkdir -m g+rwxs X.Y.Z
 151       cd X.Y.Z
 152       tar -xjvf ~/docutils-docs.tar.bz2
 153       rm ~/docutils-docs.tar.bz2
 154
 155 * Upload the release tarball, release.sh tries with scp.
 156
 157 * Access the _`file release system` on SourceForge (Admin
 158   interface).
 159
 160   ``https://sourceforge.net/projects/docutils/files/docutils/``
 161
 162   * change into the released version's directory
 163   * click ``(i)`` button of the tar.gz-file
 164   * select as default download for all operating systems.
 165
 166 * Submit a notification on project news.
 167
 168 * For verifying the integrity of the release, download the release
 169   tarball (you may need to wait up to 30 minutes), install_ it, and
 170   re-run the `test suite`_.
 171
 172 * Register with PyPI (``python setup.py register``).
 173
 174   Set the download-url so eggs can access older releases.
 175
 176   _`create and upload wheels`:
 177
 178 * The `Python Packaging User Guide` recommends to provide `wheels`_ [#]_ in
 179   addition to the source tarball.
 180
 181   .. [#] A Built Distribution format introduced by pypa:PEP427s, which is
 182      intended to replace the Egg format. Wheel is currently supported by
 183      pip__.
 184
 185   .. _wheels: https://packaging.python.org/en/latest/distributing.html#wheels
 186   __ https://pypi.python.org/pypi/pip/
 187
 188   See also `feature request 43
 189   <https://sourceforge.net/p/docutils/feature-requests/43/>`__
 190
 191   For current Docutils, this would mean `pure Python wheels`__ for Python 2
 192   and 3 respectively.
 193
 194   __ https://packaging.python.org/en/latest/distributing.html#pure-python-wheels
 195
 196
 197   + Eventually install the `wheel <https://pypi.python.org/pypi/wheel/>`__
 198     package::
 199
 200        pip install wheel
 201
 202   + Produce wheels for Python 2 and Python 3::
 203
 204        python2 setup.py bdist_wheel
 205        python3 setup.py bdist_wheel
 206
 207   + `Upload to PyPI`__
 208
 209   __ https://packaging.python.org/en/latest/distributing.html#upload-your-distributions
 210
 211
 212 * Restore ``__version_details__`` in docutils/docutils/__init__.py to
 213   "repository" (from "release").
 214
 215 * Bump the `version number`_ again.
 216
 217 * Add a new empty section "Changes Since ..." in HISTORY.txt.
 218
 219 * Update the web page (web/index.txt).
 220
 221 * Run docutils-update on the server.
 222
 223 * **Run alltests.py with svn version**
 224
 225 * **Send announcement email to:**
 226
 227   * docutils-develop@lists.sourceforge.net (also announcing the end of
 228     the check-in freeze)
 229   * docutils-users@lists.sourceforge.net
 230   * doc-sig@python.org
 231   * python-announce@python.org
 232
 233 * **Add a SourceForge News item, with title "Docutils X.Y.Z released"
 234   and containing the release tarball's download URL.**
 235
 236   **Mark as default download for all platforms.**
 237
 238 * **Register with freecode.** Add a new release for the
 239   `Docutils project`__. (freecode is freshmeat.net's new name)
 240
 241   __ http://freecode.com/projects/docutils/
 242
 243
 244 \f
 245 ..
 246    Local Variables:
 247    mode: indented-text
 248    indent-tabs-mode: nil
 249    sentence-end-double-space: t
 250    fill-column: 70
 251    End: