|
|
============================= |
|
|
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:
|
|
|
|
