|
|
|
|
|
=============================
|
|
|
|
|
|
Docutils_ Release Procedure
|
|
|
|
|
|
=============================
|
|
|
|
|
|
|
|
|
|
|
|
:Authors: David Goodger; Lea Wiemann; open to all Docutils developers
|
|
|
|
|
|
:Contact: docutils-develop@lists.sourceforge.net
|
|
|
|
|
|
:Date: $Date: 2017-08-03 11:00:21 +0200 (Do, 03 Aug 2017) $
|
|
|
|
|
|
:Revision: $Revision: 8146 $
|
|
|
|
|
|
:Copyright: This document has been placed in the public domain.
|
|
|
|
|
|
|
|
|
|
|
|
.. _Docutils: http://docutils.sourceforge.net/
|
|
|
|
|
|
|
|
|
|
|
|
Assumptions and their failure
|
|
|
|
|
|
-----------------------------
|
|
|
|
|
|
|
|
|
|
|
|
On the test machine python2.4, 2.5, 2.6, 2.7 and 3.2, 3.3, and 3.4
|
|
|
|
|
|
are installed.
|
|
|
|
|
|
Some in /usr/ some under /usr/local.
|
|
|
|
|
|
|
|
|
|
|
|
Assumption: If python2.6 is in /usr/bin/ then site-packages is under
|
|
|
|
|
|
/usr/local/lib/python2.6.
|
|
|
|
|
|
|
|
|
|
|
|
On new ubuntu 12.10
|
|
|
|
|
|
|
|
|
|
|
|
* python2.7 is here /usr/bin/python2.7.
|
|
|
|
|
|
* in /usr/lib are python2.7, pymodules and pyshared.
|
|
|
|
|
|
|
|
|
|
|
|
in /usr/lib/python2.7 no site-packages directory even after installation
|
|
|
|
|
|
of docutils
|
|
|
|
|
|
|
|
|
|
|
|
in /usr/local/lib/python2.7 are dist-packages site-packages.
|
|
|
|
|
|
|
|
|
|
|
|
site-packages is empty.
|
|
|
|
|
|
|
|
|
|
|
|
docutils is installed under dist-packages.
|
|
|
|
|
|
|
|
|
|
|
|
pymodules has a python2.7 directory.
|
|
|
|
|
|
|
|
|
|
|
|
Releasing
|
|
|
|
|
|
---------
|
|
|
|
|
|
|
|
|
|
|
|
Version numbers
|
|
|
|
|
|
~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
|
|
Version numbers shall follow the `Docutils Project Policies`_ and comply
|
|
|
|
|
|
with `PEP 440`_.
|
|
|
|
|
|
|
|
|
|
|
|
Especially, mark pre-releases and the repository version/snapshots as
|
|
|
|
|
|
"between" releases (cf. `Feature Request #50`_ and the discussion on
|
|
|
|
|
|
docutils-devel on May 28 2017), e.g.
|
|
|
|
|
|
|
|
|
|
|
|
| prev. release 0.13.1,
|
|
|
|
|
|
| prerelease 0.14rc1,
|
|
|
|
|
|
| [prereleases 0.14rc2, ...]
|
|
|
|
|
|
| release 0.14,
|
|
|
|
|
|
| repo/snapshots 0.15.dev
|
|
|
|
|
|
| [bugfix relases 0.14.1, ...] # branches off of the 0.14 release.
|
|
|
|
|
|
|
|
|
|
|
|
The repository version number is always equal to the last released
|
|
|
|
|
|
version + 1, with a .dev suffix: ``<major>.<minor+1>.dev``.
|
|
|
|
|
|
(Exception: during "feature freeze" between pre-release and release it may
|
|
|
|
|
|
point to the next pre-release.)
|
|
|
|
|
|
|
|
|
|
|
|
.. _Docutils Project Policies: policies.html#version-numbers
|
|
|
|
|
|
.. _Feature Request #50: https://sourceforge.net/p/docutils/feature-requests/50/
|
|
|
|
|
|
.. _PEP 440: https://www.python.org/dev/peps/pep-0440/
|
|
|
|
|
|
|
|
|
|
|
|
Release steps
|
|
|
|
|
|
~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
|
|
REWORK FOR SOURCEFORGE REPO
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. WARNING:: Steps in boldface text are *not* covered by the release script
|
|
|
|
|
|
at sandbox/infrastructure/release.sh. "Not covered" means that you
|
|
|
|
|
|
aren't even reminded of them.
|
|
|
|
|
|
|
|
|
|
|
|
.. Note:: This document does not cover branching and tagging, but the
|
|
|
|
|
|
release script does.
|
|
|
|
|
|
|
|
|
|
|
|
.. Note:: You may want to use ReleaseForge_ instead of using
|
|
|
|
|
|
SourceForge's file release system.
|
|
|
|
|
|
|
|
|
|
|
|
.. _ReleaseForge: http://releaseforge.sourceforge.net/
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
* **On the Docutils-develop mailing list, announce that the release is
|
|
|
|
|
|
going to be made, update the release notes and ask for additions.**
|
|
|
|
|
|
|
|
|
|
|
|
**Announce the date of the feature freeze, at least a week away.**
|
|
|
|
|
|
|
|
|
|
|
|
Consult HISTORY.TXT for changes.
|
|
|
|
|
|
|
|
|
|
|
|
* **Announce a check-in freeze on Docutils-develop.**
|
|
|
|
|
|
|
|
|
|
|
|
* **Announce the upcoming release at the Sphinx-devel mailing list
|
|
|
|
|
|
and ask for testing with Sphinx.**
|
|
|
|
|
|
(This step can be skipped for bugfix releases.)
|
|
|
|
|
|
|
|
|
|
|
|
* update `version numbers`_:
|
|
|
|
|
|
|
|
|
|
|
|
We want pre-release tags ``rcN`` for pre-releases, development release tag
|
|
|
|
|
|
``.dev`` for snapshots and installs from the repository.
|
|
|
|
|
|
|
|
|
|
|
|
For a prerelease
|
|
|
|
|
|
|
|
|
|
|
|
0. before release ``<next-release-number>.dev``
|
|
|
|
|
|
1. set this to ``<next-release-number>.rc1``
|
|
|
|
|
|
2. release
|
|
|
|
|
|
3. increase prerelease number in the repository
|
|
|
|
|
|
|
|
|
|
|
|
For a release
|
|
|
|
|
|
|
|
|
|
|
|
0. before release ``<next-release-number>.dev`` or
|
|
|
|
|
|
``<next-release-number>.rc<N>``
|
|
|
|
|
|
1. set this to ``<next-release-number>`` without prerelease character.
|
|
|
|
|
|
2. release
|
|
|
|
|
|
3. set to ``<major>.<minor+1>.dev`` in the repository (trunk).
|
|
|
|
|
|
|
|
|
|
|
|
see what ``sandbox/infrastructure/release.sh`` can aid
|
|
|
|
|
|
|
|
|
|
|
|
Call ``sandbox/infrastructure/set_release.sh new_version``.
|
|
|
|
|
|
For details see the script.
|
|
|
|
|
|
|
|
|
|
|
|
``new_version`` is major.minor[.micro][<pre>][.dev]
|
|
|
|
|
|
|
|
|
|
|
|
.. Note:: *BUG* test tarball requires root password, but it is possible to
|
|
|
|
|
|
skip this stage interactively, and testing should be done before
|
|
|
|
|
|
release.
|
|
|
|
|
|
|
|
|
|
|
|
* Change ``__version_details__`` in docutils/docutils/__init__.py to
|
|
|
|
|
|
"release" (from "repository").
|
|
|
|
|
|
|
|
|
|
|
|
* Check the _`version number` in the following files, should be already
|
|
|
|
|
|
correct:
|
|
|
|
|
|
|
|
|
|
|
|
+ docutils/setup.py
|
|
|
|
|
|
+ docutils/docutils/__init__.py
|
|
|
|
|
|
+ docutils/test/functional/expected/* ("Generator: Docutils X.Y[.Z]")
|
|
|
|
|
|
+ docutils/README.txt
|
|
|
|
|
|
+ web/index.txt
|
|
|
|
|
|
|
|
|
|
|
|
* Close the "Changes Since ..." section in docutils/HISTORY.txt.
|
|
|
|
|
|
|
|
|
|
|
|
* Clear/unset the PYTHONPATH environment variable.
|
|
|
|
|
|
|
|
|
|
|
|
* Create the release tarball:
|
|
|
|
|
|
|
|
|
|
|
|
(a) Create a new empty directory and ``cd`` into it.
|
|
|
|
|
|
|
|
|
|
|
|
(b) Get a clean snapshot of the main tree::
|
|
|
|
|
|
|
|
|
|
|
|
svn export svn://svn.code.sf.net/p/docutils/code/trunk/docutils
|
|
|
|
|
|
|
|
|
|
|
|
or via the [Download Snapshot] button at
|
|
|
|
|
|
http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
|
|
|
|
|
|
|
|
|
|
|
|
(c) Use Distutils to create the release tarball::
|
|
|
|
|
|
|
|
|
|
|
|
cd docutils
|
|
|
|
|
|
python setup.py sdist
|
|
|
|
|
|
|
|
|
|
|
|
* Expand and _`install` the release tarball in isolation:
|
|
|
|
|
|
|
|
|
|
|
|
(a) Expand the tarball in a new location, not over any existing
|
|
|
|
|
|
files.
|
|
|
|
|
|
|
|
|
|
|
|
(b) Remove the old installation from site-packages (including
|
|
|
|
|
|
roman.py, and optparse.py, textwrap.py).
|
|
|
|
|
|
|
|
|
|
|
|
"remove" might fail, see _`Assumptions and their failure`
|
|
|
|
|
|
|
|
|
|
|
|
Install from expanded directory::
|
|
|
|
|
|
|
|
|
|
|
|
cd docutils-X.Y.Z
|
|
|
|
|
|
python setup.py install
|
|
|
|
|
|
|
|
|
|
|
|
The "install" command may require root permissions.
|
|
|
|
|
|
|
|
|
|
|
|
(c) Repeat step b) for all supported Python versions.
|
|
|
|
|
|
|
|
|
|
|
|
* Run the _`test suite` from the expanded archive directory with all
|
|
|
|
|
|
supported Python versions on all available platforms (GNU/Linux, Mac
|
|
|
|
|
|
OS X, Windows)::
|
|
|
|
|
|
|
|
|
|
|
|
cd test ; python -u alltests.py
|
|
|
|
|
|
|
|
|
|
|
|
* Add a directory X.Y.Z (where X.Y.Z is the current version number
|
|
|
|
|
|
of Docutils) in the webroot (i.e. the ``htdocs/`` directory).
|
|
|
|
|
|
Put all documentation files into it::
|
|
|
|
|
|
|
|
|
|
|
|
cd docutils-X.Y.Z
|
|
|
|
|
|
rm -rf build
|
|
|
|
|
|
cd tools/
|
|
|
|
|
|
./buildhtml.py ..
|
|
|
|
|
|
cd ..
|
|
|
|
|
|
find -name test -type d -prune -o -name \*.css -print0 \
|
|
|
|
|
|
-o -name \*.html -print0 -o -name \*.txt -print0 \
|
|
|
|
|
|
| tar -cjvf docutils-docs.tar.bz2 -T - --null
|
|
|
|
|
|
scp docutils-docs.tar.bz2 <username>@shell.sourceforge.net:
|
|
|
|
|
|
|
|
|
|
|
|
Now log in to shell.sourceforge.net and::
|
|
|
|
|
|
|
|
|
|
|
|
cd /home/groups/d/do/docutils/htdocs/
|
|
|
|
|
|
mkdir -m g+rwxs X.Y.Z
|
|
|
|
|
|
cd X.Y.Z
|
|
|
|
|
|
tar -xjvf ~/docutils-docs.tar.bz2
|
|
|
|
|
|
rm ~/docutils-docs.tar.bz2
|
|
|
|
|
|
|
|
|
|
|
|
* Upload the release tarball, release.sh tries with scp.
|
|
|
|
|
|
|
|
|
|
|
|
* Access the _`file release system` on SourceForge (Admin
|
|
|
|
|
|
interface).
|
|
|
|
|
|
|
|
|
|
|
|
``https://sourceforge.net/projects/docutils/files/docutils/``
|
|
|
|
|
|
|
|
|
|
|
|
* change into the released version's directory
|
|
|
|
|
|
* click ``(i)`` button of the tar.gz-file
|
|
|
|
|
|
* select as default download for all operating systems.
|
|
|
|
|
|
|
|
|
|
|
|
* Submit a notification on project news.
|
|
|
|
|
|
|
|
|
|
|
|
* For verifying the integrity of the release, download the release
|
|
|
|
|
|
tarball (you may need to wait up to 30 minutes), install_ it, and
|
|
|
|
|
|
re-run the `test suite`_.
|
|
|
|
|
|
|
|
|
|
|
|
* Register with PyPI (``python setup.py register``).
|
|
|
|
|
|
|
|
|
|
|
|
Set the download-url so eggs can access older releases.
|
|
|
|
|
|
|
|
|
|
|
|
* Restore ``__version_details__`` in docutils/docutils/__init__.py to
|
|
|
|
|
|
"repository" (from "release").
|
|
|
|
|
|
|
|
|
|
|
|
* Bump the `version number`_ again.
|
|
|
|
|
|
|
|
|
|
|
|
* Add a new empty section "Changes Since ..." in HISTORY.txt.
|
|
|
|
|
|
|
|
|
|
|
|
* Update the web page (web/index.txt).
|
|
|
|
|
|
|
|
|
|
|
|
* Run docutils-update on the server.
|
|
|
|
|
|
|
|
|
|
|
|
* **Run alltests.py with svn version**
|
|
|
|
|
|
|
|
|
|
|
|
* **build wheels**::
|
|
|
|
|
|
|
|
|
|
|
|
pip wheel docutils
|
|
|
|
|
|
pip3 wheel docutils
|
|
|
|
|
|
|
|
|
|
|
|
This builds wheels_ (`pure Python wheels`_ for Python 2 and 3
|
|
|
|
|
|
respectively) by downloading the new release from pypi.
|
|
|
|
|
|
|
|
|
|
|
|
`Upload the wheels to PyPI`_.
|
|
|
|
|
|
|
|
|
|
|
|
Question:
|
|
|
|
|
|
Can we have an tar.gz (distutil) and a py2-wheel and a py3-wheel
|
|
|
|
|
|
on pypi and will installers select the correct files?
|
|
|
|
|
|
|
|
|
|
|
|
2017-06-09 it seems to according to experience with 0.13.1.
|
|
|
|
|
|
|
|
|
|
|
|
.. _wheels: https://packaging.python.org/en/latest/distributing.html#wheels
|
|
|
|
|
|
.. _pure Python wheels:
|
|
|
|
|
|
https://packaging.python.org/en/latest/distributing.html#pure-python-wheels
|
|
|
|
|
|
.. _Upload the wheels to PyPI:
|
|
|
|
|
|
https://packaging.python.org/en/latest/distributing.html#upload-your-distributions
|
|
|
|
|
|
|
|
|
|
|
|
* **Send announcement email to:**
|
|
|
|
|
|
|
|
|
|
|
|
* docutils-develop@lists.sourceforge.net (also announcing the end of
|
|
|
|
|
|
the check-in freeze)
|
|
|
|
|
|
* docutils-users@lists.sourceforge.net
|
|
|
|
|
|
* doc-sig@python.org
|
|
|
|
|
|
* python-announce@python.org
|
|
|
|
|
|
|
|
|
|
|
|
* **Add a `SourceForge News item`__, with title "Docutils X.Y.Z released"**
|
|
|
|
|
|
|
|
|
|
|
|
__ https://sourceforge.net/p/docutils/news
|
|
|
|
|
|
|
|
|
|
|
|
**Mark as default download for all platforms.**
|
|
|
|
|
|
|
|
|
|
|
|
* **Register with freecode.** Add a new release for the
|
|
|
|
|
|
`Docutils project`__. (freecode is freshmeat.net's new name)
|
|
|
|
|
|
|
|
|
|
|
|
__ http://freecode.com/projects/docutils/
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
..
|
|
|
|
|
|
Local Variables:
|
|
|
|
|
|
mode: indented-text
|
|
|
|
|
|
indent-tabs-mode: nil
|
|
|
|
|
|
sentence-end-double-space: t
|
|
|
|
|
|
fill-column: 70
|
|
|
|
|
|
End:
|
