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