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 Version numbers
  43 ~~~~~~~~~~~~~~~
  44
  45 Version numbers shall follow the `Docutils Project Policies`_ and comply
  46 with `PEP 440`_.
  47
  48 From `Feature Request #50`_
  49
  50   PEP 440 specifies how release version are understood by pip and other tools.
  51
  52   The last released package of docutils was in 2014.
  53
  54   If you install the version from Source it will not be overriden by version
  55   0.13 when it is eventaully released.
  56
  57   As folks have installed 0.13 from indeterminate source versions the current
  58   version should be incremented as to allow pip to overrite a 0.13 snapshot
  59   when the next official release.
  60
  61   Please increment and switch the version in setup.py to be a pre-release.
  62   e.g. 0.13.1a
  63
  64   When a version is tagged it should be changed to a non pre release and then
  65   in the next commit incremented to the next expected version but with a pre
  66   release added ::
  67
  68     0.13.1a -> Head
  69     0.13.1 -> when tagged for release
  70     0.13.2a -> new head after release
  71
  72   Additionally snapshots can be marked with the .devXXX nomenclature.
  73
  74   These can then all be pushed to pypi.python.org and by default pip will
  75   install the latest release unless explicitly requested via the ``--pre``
  76   flag or a version specifier ``docutils>=0.13.1a``
  77
  78 .. _Docutils Project Policies: policies.html#version-numbers
  79 .. _Feature Request #50: https://sourceforge.net/p/docutils/feature-requests/50/
  80 .. _PEP 440: https://www.python.org/dev/peps/pep-0440/
  81
  82 Release steps
  83 ~~~~~~~~~~~~~
  84
  85 REWORK FOR SOURCEFORGE REPO
  86
  87
  88 .. WARNING:: Steps in boldface text are *not* covered by the release script
  89    at sandbox/infrastructure/release.sh.  "Not covered" means that you
  90    aren't even reminded of them.
  91
  92 .. Note:: This document does not cover branching and tagging, but the
  93    release script does.
  94
  95 .. Note:: You may want to use ReleaseForge_ instead of using
  96    SourceForge's file release system.
  97
  98    .. _ReleaseForge: http://releaseforge.sourceforge.net/
  99
 100
 101 * **On the Docutils-develop mailing list, announce that the release is
 102   going to be made, update the release notes and ask for additions.**
 103
 104   Consult HISTORY.TXT for changes.
 105
 106 * **Announce a check-in freeze on Docutils-develop.**
 107
 108 * **Announce the upcoming release at the Sphinx-devel mailing list
 109   and ask for testing with Sphinx.**
 110   (This step can be skipped for bugfix releases.)
 111
 112 * THIS CHANGES for new numbering:
 113
 114   we want:
 115
 116   the release-number might include a prerelease character
 117   ``a``, ``b``, or ``c`` or ``rc1``.
 118
 119   for a prerelease
 120
 121   0. before release ``repository <next-release-number>``
 122   1. set this to ``prerelease <next-release-number>``
 123   2. release
 124   3. increase prerelease character, set to text repository
 125
 126   for a release
 127
 128   0. before release ``repository <next-release-number>``
 129   1. set this to ``release <next-release-number>``
 130      without prerelease character.
 131   2. release
 132   3. set prerelease character ``a``, set to text repository
 133
 134   see what ``sandbox/infrastructure/release.sh`` can aid
 135
 136   Call ``sandbox/infrastructure/release.sh new_version svn_version``.
 137   For details see the script.
 138
 139   ``new_version`` is the current version, status will change from
 140   ``repository`` to ``release``. ``svn_version`` is the version after
 141   release.
 142
 143   .. Note:: *BUG* test tarball requires root password, but it is possible to
 144      skip this stage interactively, and testing should be done before
 145      release.
 146
 147 * Change ``__version_details__`` in docutils/docutils/__init__.py to
 148   "release" (from "repository").
 149
 150 * Check the _`version number` in the following files, should be already
 151   correct:
 152
 153   + docutils/setup.py
 154   + docutils/docutils/__init__.py
 155   + docutils/test/functional/expected/* ("Generator: Docutils X.Y.Z")
 156   + docutils/README.txt
 157   + web/index.txt
 158
 159 * Close the "Changes Since ..." section in docutils/HISTORY.txt.
 160
 161 * Clear/unset the PYTHONPATH environment variable.
 162
 163 * Create the release tarball:
 164
 165   (a) Create a new empty directory and ``cd`` into it.
 166
 167   (b) Get a clean snapshot of the main tree::
 168
 169           svn export svn://svn.code.sf.net/p/docutils/code/trunk/docutils
 170
 171       or via the [Download Snapshot] button at
 172       http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
 173
 174   (c) Use Distutils to create the release tarball::
 175
 176           cd docutils
 177           python setup.py sdist
 178
 179 * Expand and _`install` the release tarball in isolation:
 180
 181   (a) Expand the tarball in a new location, not over any existing
 182       files.
 183
 184   (b) Remove the old installation from site-packages (including
 185       roman.py, and optparse.py, textwrap.py).
 186
 187       "remove" might fail, see _`Assumptions and their failure`
 188
 189       Install from expanded directory::
 190
 191           cd docutils-X.Y.Z
 192           python setup.py install
 193
 194       The "install" command may require root permissions.
 195
 196   (c) Repeat step b) for all supported Python versions.
 197
 198 * Run the _`test suite` from the expanded archive directory with all
 199   supported Python versions on all available platforms (GNU/Linux, Mac
 200   OS X, Windows)::
 201
 202       cd test ; python -u alltests.py
 203
 204 * Add a directory X.Y.Z (where X.Y.Z is the current version number
 205   of Docutils) in the webroot (i.e. the ``htdocs/`` directory).
 206   Put all documentation files into it::
 207
 208       cd docutils-X.Y.Z
 209       rm -rf build
 210       cd tools/
 211       ./buildhtml.py ..
 212       cd ..
 213       find -name test -type d -prune -o -name \*.css -print0 \
 214           -o -name \*.html -print0 -o -name \*.txt -print0 \
 215           | tar -cjvf docutils-docs.tar.bz2 -T - --null
 216       scp docutils-docs.tar.bz2 <username>@shell.sourceforge.net:
 217
 218   Now log in to shell.sourceforge.net and::
 219
 220       cd /home/groups/d/do/docutils/htdocs/
 221       mkdir -m g+rwxs X.Y.Z
 222       cd X.Y.Z
 223       tar -xjvf ~/docutils-docs.tar.bz2
 224       rm ~/docutils-docs.tar.bz2
 225
 226 * Upload the release tarball, release.sh tries with scp.
 227
 228 * Access the _`file release system` on SourceForge (Admin
 229   interface).
 230
 231   ``https://sourceforge.net/projects/docutils/files/docutils/``
 232
 233   * change into the released version's directory
 234   * click ``(i)`` button of the tar.gz-file
 235   * select as default download for all operating systems.
 236
 237 * Submit a notification on project news.
 238
 239 * For verifying the integrity of the release, download the release
 240   tarball (you may need to wait up to 30 minutes), install_ it, and
 241   re-run the `test suite`_.
 242
 243 * Register with PyPI (``python setup.py register``).
 244
 245   Set the download-url so eggs can access older releases.
 246
 247 * Restore ``__version_details__`` in docutils/docutils/__init__.py to
 248   "repository" (from "release").
 249
 250 * Bump the `version number`_ again.
 251
 252 * Add a new empty section "Changes Since ..." in HISTORY.txt.
 253
 254 * Update the web page (web/index.txt).
 255
 256 * Run docutils-update on the server.
 257
 258 * **Run alltests.py with svn version**
 259
 260 * **build wheels**::
 261
 262     pip wheel docutils
 263     pip3 wheel docutils
 264
 265   This builds wheels_ (`pure Python wheels`_ for Python 2 and 3
 266   respectively) by downloading the new release from pypi.
 267
 268   `Upload the wheels to PyPI`_.
 269
 270   Question: Can we have an tar.gz (distutil) and a py2-wheel and a py3-wheel
 271     on pypi and will installers select the correct files ?
 272
 273
 274   .. _wheels: https://packaging.python.org/en/latest/distributing.html#wheels
 275   .. _pure Python wheels:
 276      https://packaging.python.org/en/latest/distributing.html#pure-python-wheels
 277   .. _Upload the wheels to PyPI:
 278      https://packaging.python.org/en/latest/distributing.html#upload-your-distributions
 279
 280 * **Send announcement email to:**
 281
 282   * docutils-develop@lists.sourceforge.net (also announcing the end of
 283     the check-in freeze)
 284   * docutils-users@lists.sourceforge.net
 285   * doc-sig@python.org
 286   * python-announce@python.org
 287
 288 * **Add a SourceForge News item, with title "Docutils X.Y.Z released"
 289   and containing the release tarball's download URL.**
 290
 291   **Mark as default download for all platforms.**
 292
 293 * **Register with freecode.** Add a new release for the
 294   `Docutils project`__. (freecode is freshmeat.net's new name)
 295
 296   __ http://freecode.com/projects/docutils/
 297
 298 \f
 299 ..
 300    Local Variables:
 301    mode: indented-text
 302    indent-tabs-mode: nil
 303    sentence-end-double-space: t
 304    fill-column: 70
 305    End: