Edit file File name : release.txt Content :============================= 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: Save