docutils/docs/dev/release.txt

   1 .. include:: ../header.txt
   2
   3 =============================
   4  Docutils_ Release Procedure
   5 =============================
   6
   7 :Authors: David Goodger; Lea Wiemann; open to all Docutils developers
   8 :Contact: docutils-develop@lists.sourceforge.net
   9 :Date: $Date$
  10 :Revision: $Revision$
  11 :Copyright: This document has been placed in the public domain.
  12
  13 .. _Docutils: https://docutils.sourceforge.io/
  14
  15 Steps to take and watch
  16 -----------------------
  17
  18 * Make a clean checkout of svn.code.sf.net/p/docutils/code/trunk/docutils
  19   to avoid having development files in the released packages.
  20
  21   Test, package and release this checkout.
  22
  23 * Announce the upcoming release on docutils-develop list.
  24
  25   Consider **feature freeze** or/and **check-in freeze** .
  26
  27 * Update RELEASE-NOTES.txt add section ``Release <version>``.
  28
  29   Consult HISTORY.txt for important changes.
  30
  31 * Change HISTORY.txt title ``Changes Since <previous release>`` to ``Release <version>``.
  32
  33 * Set new version (replace ``<version>`` with the new version indentifier
  34   and ``<docutils-repository-root>`` with the dir containing
  35   ``HISTORY.txt`` and ``RELEASE-NOTES.txt``)::
  36
  37       cd <docutils-repository-root>
  38       ../sandbox/infrastructure/set_version.sh <version>
  39
  40   Check what was changed by ``set_version.sh``.
  41
  42   Change acchordingly docutils/__init__.py ::
  43
  44     __version_info__ = VersionInfo(
  45         major=0,
  46         minor=21,
  47         micro=0,
  48         releaselevel='candidate',  # one of 'alpha', 'beta', 'candidate', 'final'
  49         serial=1,  # pre-release number (0 for final releases and snapshots)
  50         release=False  # True for official releases and pre-releases
  51         )
  52
  53
  54   Run tests ::
  55
  56     export PYTHONWARNINGS=default
  57     python3 test/alltests.py
  58
  59   or use tox.
  60   In case of errors, clearing ``docutils/__pycache__`` may help.
  61
  62   ``export PYTHONWARNINGS=default`` prints DeprecationWarnings in python3.
  63
  64 * Generate wheel and source-distribution::
  65
  66     python3 -m pip install flit
  67     python3 -m flit build
  68
  69   or ::
  70
  71     python3 -m pip install build
  72     python3 -m build .
  73
  74   check file sizes: the 0.21.2 wheel was 574K the sdist 2,2M.
  75
  76 * Upload wheel and source to test.pypi.
  77
  78   Set repository and key in ~/.pypirc with a <server-name> and
  79   password token::
  80
  81     python3 -m twine upload --repository <server-name> dist/*
  82
  83   Change directory outside of checkout and test in venv.
  84   NOTE use --pre for prereleases::
  85
  86     python3 -m venv du3 ; cd du3
  87     export PYTHONPATH= ; . bin/activate
  88
  89     pip install --index-url https://test.pypi.org/simple/ --no-deps docutils
  90
  91     cp -Lr ../docutils-code/docutils/test .
  92     python test/alltests.py
  93
  94   Ignore missing HISTORY.txt it is not in the wheel file.
  95   if ok ::
  96
  97     deactivate ; cd .. ; rm -r du3
  98
  99   Test the sdist::
 100
 101     python3 -m venv du3s ; cd du3s
 102     export PYTHONPATH= ; . bin/activate
 103
 104     pip install --index-url https://test.pypi.org/simple/ --no-binary docutils docutils
 105
 106   sdist installation fails with subprocess not finding flit_core .
 107   test.pypi has flit 3.5.1 but installs 0.5 preinstalling flit_core did not work
 108   either ... why.
 109
 110   postbone sdist test to pypi::
 111
 112     cp -Lr ../docutils-code/docutils/test .
 113     python test/alltests.py
 114
 115   Ignore ``test_find_file_in_dirs`` fails because HISTORY.txt is missing or/and
 116   missing pil.
 117
 118     deactivate ; cd .. ; rm -r du3s
 119
 120 * Commit changes ... the changed version number.
 121
 122 * If final release tag #.# (Note: only directory docutils is copied)::
 123
 124     svn copy svn+ssh://grubert@svn.code.sf.net/p/docutils/code/trunk/docutils \
 125              svn+ssh://grubert@svn.code.sf.net/p/docutils/code/tags/docutils-#.# \
 126              -m "tagging release #.#"
 127
 128 * Update your source directory.
 129 * Rebuild wheel and source-distribution ::
 130
 131     python3 -m flit build
 132
 133 * Now upload to pypi::
 134
 135     python3 -m twine upload --repository <server-name> dist/docutils-#.#*
 136
 137 * Remove previous package from local cache::
 138
 139     find .cache/pip/wheels -name docutils\*whl -exec rm -v -i {} \;
 140
 141 * Test the sdist::
 142
 143     python3 -m venv du3s ; cd du3s
 144     export PYTHONPATH= ; . bin/activate
 145
 146     pip install --no-binary docutils docutils
 147
 148     cp -Lr ../docutils-code/docutils/test .
 149     python test/alltests.py
 150
 151   Ignore ``test_find_file_in_dirs`` fails because HISTORY.txt is missing.
 152
 153     deactivate ; cd .. ; rm -r du3s
 154
 155 * and wheel::
 156
 157     python3 -m venv du3 ; cd du3
 158     export PYTHONPATH= ; . bin/activate
 159
 160     pip install --no-deps docutils
 161     cp -Lr ../docutils-code/docutils/test .
 162     python test/alltests.py
 163
 164     deactivate ; cd .. ; rm -r du3
 165
 166 * Notify to docutils-developer and user.
 167
 168 For candidate releases change version to rc#+1dev.
 169
 170 For final releases continue
 171
 172 * upload source and generated html to sf-htdocs/#.# ::
 173
 174     mkdir tmp1
 175     cd tmp1
 176     tar xzvf ../dist/docutils-#.#.tar.gz
 177     cd docutils-#.#/
 178     python3 tools/buildhtml.py .
 179     find . -name \*.pyc -exec rm -v {} \;
 180     find . -name __pycache__ -exec rmdir -v {} \;
 181     rsync -e ssh -r -t ./ web.sourceforge.net:/home/project-web/docutils/htdocs/#.#
 182
 183 * Check web/index.txt for necessary corrections.
 184 * Run sandbox/infrastructure/docutils-update.local to update web-content.
 185 * Release to sourceforge.
 186
 187   - Upload docutils-#.#.tar.gz and release notes to sourceforge.
 188   - Select docutils-#.#.tar.gz as default for all OS.
 189
 190 * set_version #.{#+1}b.dev
 191 * docutils/HISTORY.txt: add title "Changes Since #.#"
 192 * run sandbox/infrastructure/docutils-update.local
 193
 194 ..\f Emacs settings
 195
 196    Local Variables:
 197    mode: indented-text
 198    mode: rst
 199    indent-tabs-mode: nil
 200    sentence-end-double-space: t
 201    fill-column: 70
 202    End: