============================= Docutils_ Release Procedure ============================= :Authors: David Goodger; Lea Wiemann; open to all Docutils developers :Contact: docutils-develop@lists.sourceforge.net :Date: $Date: 2015-05-08 15:56:32 +0000 (Fri, 08 May 2015) $ :Revision: $Revision: 7889 $ :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/ than 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 --------- REWORK FOR SOURCEFORGE REPO 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.** Consult HISTORY.TXT for changes. * **Announce a check-in freeze on Docutils-develop.** Call ``sandbox/infrastructure/release.sh new_version svn_version``. For details see the script. ``new_version`` is the current version, status will change from ``repository`` to ``release``. ``svn_version`` is the version after release. .. 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 .. note:: PyPI recommends to `create and upload wheels`_ in addition to the source tarball. * 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 @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. _`create and upload wheels`: * The `Python Packaging User Guide` recommends to provide `wheels`_ [#]_ in addition to the source tarball. .. [#] A Built Distribution format introduced by pypa:PEP427s, which is intended to replace the Egg format. Wheel is currently supported by pip__. .. _wheels: https://packaging.python.org/en/latest/distributing.html#wheels __ https://pypi.python.org/pypi/pip/ See also `feature request 43 `__ For current Docutils, this would mean `pure Python wheels`__ for Python 2 and 3 respectively. __ https://packaging.python.org/en/latest/distributing.html#pure-python-wheels + Eventually install the `pip `__` and `wheel `__ packages. + Produce wheels: For the default Python version: - From release at PyPI :: pip wheel docutils - From working directory's sub-directory "docutils" :: pip wheel ./docutils/ Under Debian, the default Python version is 2.7 and the wheel is usable for all 2.x versions supported by Docutils and the command ``pip3 wheel docutils`` generates a wheel suitable for Py3k. + `Upload to PyPI`__ __ https://packaging.python.org/en/latest/distributing.html#upload-your-distributions * 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** * **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" and containing the release tarball's download URL.** **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/ * **build a wheel** at least for python3:: pip3 wheel docutils This builds the wheel by downloading the new release from pypi. Upload the wheel 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 ? .. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End: