wiki:ReleaseProcess

Context Navigation

Version 160 (modified by therve, 5 years ago) (diff)
--

This document describes the Twisted release process. Although it is still incomplete, every effort has been made to ensure that it is accurate and up-to-date. There are plans to eventually move this document into the source tree (#4543).

This process has only been tested on Linux, so we recommend that you do the release on Linux.

Outcomes

By the end of a Twisted release we'll have:

Tarballs for Twisted as a whole, and for each of its sub-projects
Windows installers for the whole Twisted project
Updated documentation (API, howtos & book) on the twistedmatrix.com site
Updated download links on the twistedmatrix.com site
Announcement emails sent to major Python lists
Announcement post on http://labs.twistedmatrix.com
A tag in our Subversion repository marking the release

Prerequisites

To release Twisted, you will need:

Commit privileges to Twisted
Shell access to cube.twistedmatrix.com
- XXX: Possibly this ought to be permission to log in as www-data
Write permissions to /srv/www-data/twisted on cube (normally, www-data membership)
Write permissions to /srv/www-data/website/vhosts/twistedmatrix.com/documents
Permissions to edit WikiStart
Channel operator permissions for #twisted
Admin privileges for Twisted's PyPI packages
Membership of https://launchpad.net/~twisted-dev
Contributor status for http://labs.twistedmatrix.com

Version numbers

Twisted releases use a time-based numbering scheme. Releases versions like YY.MM.mm, where YY is the last two digits of the year of the release, MM is the number of the release in the year, and mm is the number of the patch release.

For example:

The first release of 2010 is 10.0.0
The second release of 2010 is 10.1.0
If 10.1.0 has some critical defects, then a patch release would be numbered 10.1.1
The first pre-release of 10.0.0 is 10.0.0pre1, the second is 10.0.0pre2

Every release of Twisted includes the whole project, the core and all sub-projects. Each of these has the same number.

Throughout this document, we'll refer to the version number of the release as $RELEASE. Examples of $RELEASE include 10.0.0, 10.1.0, 10.1.1 etc.

We'll refer to the first two components of the release as $API, since all releases that share those numbers are mutually API compatible. e.g. for 10.0.0, $API is 10.0; for 10.1.0 and 10.1.1, $API is 10.1.

The change-versions script automatically picks the right number for you. Please retrieve it after you run it.

Overview

To release Twisted, we

Prepare for a release
Release N pre-releases
Release the final release

Prepare for a release

Check the milestone for the upcoming release
1. Get rid of any non-critical bugs
2. Get any critical bugs fixed
Check for any regressions
Read through the INSTALL and README files to make sure things like the supported Python versions are correct
1. Check the required Python version.
2. Check that the list matches the current set of buildbots.
3. Any mistakes should be fixed in trunk before making the release branch
Choose a version number. Remember to include the 'preN' suffix
File a ticket
1. Assign it to the upcoming release milestone
2. Assign it to yourself
3. Call it "Release $RELEASE"
Make a branch (e.g. mkbranch Twisted releases/release-$RELEASE-4290)

How to do a pre-release

Check buildbot to make sure all supported platforms are green (wait for pending builds if necessary).
If a previously supported platform does not currently have a buildbot, move from supported platforms to "expected to work" in INSTALL. (Pending #1305)
Run ./bin/admin/change-versions --prerelease
Commit the changes made by change-versions
Run ./bin/admin/build-news .
Commit the changes made by build-news
~~Delete the NEWS turds (see #4315)~~
Bump copyright dates in LICENSE, twisted/copyright.py, and README
Make a temporary directory for the tarballs to live in (e.g. mkdir /tmp/twisted-release)
Run ./bin/admin/build-tarballs . /tmp/twisted-release/
1. Note: build-tarballs does not produce exactly the same output when run multiple times, even when nothing else has changed. If a problem is encountered that requires build-tarballs to be re-run (either during the pre-release or later during the release), care must be taken to avoid releasing two or more different versions of the tarball.
Upload the tarballs to a public website (see #4353)
Write the pre-release announcement
1. Read through the NEWS file and summarize the interesting changes for the release
2. Get someone else to look over the announcement before doing it
Announce the pre-release on
1. the twisted-python mailing list
2. on IRC in the #twisted topic
3. in a blog post, ideally labs.twistedmatrix.com

Pre-release announcement

The pre-release announcement should mention the important changes since the last release, and exhort readers to test this pre-release.

Here's what the $RELEASEpre1 release announcement might look like:

Live from PyCon Atlanta, I'm pleased to herald the approaching
footsteps of the $API release.

Tarballs for the first Twisted $RELEASE pre-release are now available at:
 http://people.canonical.com/~jml/Twisted/

Highlights include:

 * Improved documentation, including "Twisted Web in 60 seconds"

 * Faster Perspective Broker applications

 * A new Windows installer that ships without zope.interface

 * Twisted no longer supports Python 2.3

 * Over one hundred closed tickets

For more information, see the NEWS file.

Please download the tarballs and test them as much as possible.

Thanks,
jml

How to do a final release

Prepare the branch

Have the release branch, previously used to generate a pre-release, checked out
Run ./bin/admin/change-versions
Add the quote of the release to the README
Make a new quote file for the next version: svn cp doc/fun/Twisted.Quotes doc/historic/Quotes/Twisted-$RELEASE; echo '' > doc/fun/Twisted.Quotes.
Commit the version and README changes.
Submit the ticket for review
Pause until the ticket is reviewed and accepted.
Tag the release
- e.g. svn cp svn+ssh://svn.twistedmatrix.com/svn/Twisted/branches/releases/release-$RELEASE-4290 svn+ssh://svn.twistedmatrix.com/svn/Twisted/tags/releases/twisted-$RELEASE
- A good commit message to use is something like "Tag $RELEASE release"

Cut the tarballs & installers

Create a new staging area for the release (e.g. mkdir /tmp/twisted-release)
Using a checkout of the release branch or the release tag (with no local changes!), run ./bin/admin/build-tarballs . /tmp/twisted-release/
Build windows installers
1. ~~http://buildbot.twistedmatrix.com/builders/winxp32-py2.5-msi/~~
2. ~~http://buildbot.twistedmatrix.com/builders/winxp32-py2.6-msi/~~
3. http://buildbot.twistedmatrix.com/builders/winxp32-py2.7-msi/
4. http://buildbot.twistedmatrix.com/builders/windows7-64-py2.7-msi
5. For "Branch" specify the tag, e.g. "tags/releases/twisted-$RELEASE"
  1. The builders use the bzr export, which doesn't mirror tags/ or branches/releases/. You may need to copy the branch elsewhere.
6. Download the latest .msi and .exe files from from http://buildbot.twistedmatrix.com/builds/twisted-packages/ and save them in the staging directory
  1. ~~The installers built from windows7-64-py2.7-msi will counter-intuitively have names that end in winxp32-py2.7.exe and winxp32-py2.7.msi. This is because of "distutils weirdness and other things".~~
Sign the tarballs and Windows installers
1. e.g. md5sum Tw* | gpg -a --clearsign > twisted-$RELEASE-md5sums.txt
2. Compare this to an example of twisted-$RELEASE-md5sums.txt

Distribute

Upload to the official upload locations (see #2888)
1. e.g. ssh cube.twistedmatrix.com mkdir -m 2775 /srv/www-data/twisted/Releases/{Twisted,Core,Conch,Lore,Mail,Names,News,Pair,Runner,Web,Words}/$API
2. e.g. scp /tmp/twisted-release/Twisted-$RELEASE.tar.bz2 cube.twistedmatrix.com:/srv/www-data/twisted/Releases/Twisted/$API/
3. For all subprojects, upload the tarballs to cube.twistedmatrix.com:/srv/www-data/twisted/Releases/$SUBPROJECT/$API/
4. Windows installers (msi and exe) go in the Twisted project
Update the permissions on cube
1. For all new directories, chmod 2775 $DIRECTORY
2. For all new files, chmod 664 $FILE
3. For all new files and directories, chgrp www-data $FILE_OR_DIR
4. e.g. On cube, find /srv/www-data/twisted/Releases -name '*$RELEASE*' | xargs chmod g+w
~~Wait for the tarballs to be mirrored to http://tmrc.mit.edu/mirror/twisted/Twisted/~~
- ~~They are mirrored 15 minutes after every hour~~
- ~~You can ask foom on #twisted to force the mirror~~

Update documentation

Get the dependencies
- Pydoctor (use lp:~twisted-dev/pydoctor/twisted-templates-2 to get google analytics templates)
- Nevow
- Epydoc (python-epydoc in Debian)
- Some version of Latex if you didn't use the Epydoc Debian/Ubuntu package or ignored the recommended packages
- netpbm (graphics conversion tools used by the book-builder)
Export the version of Twisted being released
- e.g. svn export svn+ssh://svn.twistedmatrix.com/svn/Twisted/tags/releases/twisted-$RELEASE
Create and run the unofficial build-docs script in an export of the release tag
1. cd twisted-$RELEASE
2. Create a build-docs.py script based on this template. Be sure to read the notes at the top of that script.
  - XXX: The script builds the docs into the current directory, mixing them up with the source files.
3. python build-docs.py
  - If you have latex errors when trying to build the book and retry, don't forget to clean tmp directories which may be leftover in doc/core/howto.
4. cp -R doc /tmp/twisted-release/
5. cd /tmp/twisted-release/doc
Make the documentation directory on cube
- e.g. ssh cube.twistedmatrix.com mkdir -m 2775 ~www-data/distributable/documentation/$RELEASE
Upload the documents to cube
- e.g. scp -r doc/* cube.twistedmatrix.com:~www-data/distributable/documentation/$RELEASE
Run the build-apidocs script to build the API docs (in an export of the release tag) and then upload them (See also APIDocs and #2891)
1. ./bin/admin/build-apidocs . ./api
2. Documentation will be generated in a directory called ./api
3. tar -cjf apidocs.tar.bz2 api
4. scp apidocs.tar.bz2 cube.twistedmatrix.com:.
5. On cube, tar -xjf apidocs.tar.bz2
6. On cube, mv apidocs ~www-data/distributable/documentation/$RELEASE/api
Copy the book
- e.g. scp book.pdf cube.twistedmatrix.com:~www-data/distributable/documentation/$RELEASE/core/howto
Update the permissions on cube
1. cd ~www-data/distributable/documentation/$RELEASE
2. find . -type d | xargs chmod 2775
3. find . -type f | xargs chmod 664
4. chgrp -R www-data .
Test the generated docs
1. Browse to http://twistedmatrix.com/documents/$RELEASE/
2. Make sure that there is content in each of the directories and that it looks good
3. Follow each link on http://twistedmatrix.com/trac/wiki/Documentation, replace current with $RELEASE (e.g. 10.0.0) and look for any obvious breakage
Change the "current" symlink
1. On cube cd ~www-data/distributable/documentation
2. On cube, rm current
3. On cube, ln -s $RELEASE current

Synchronize Trac

The site uses the ProjectVersion macro to automatically adjust the links on the wiki pages, including WikiStart and Downloads, by parsing the latest twisted-$RELEASE-md5sums.txt:
1. scp twisted-$RELEASE-md5sums.txt cube.twistedmatrix.com:/srv/www-data/twisted/Releases/

Announce

Update Downloads pages
1. The following steps are automatic, due to the use of the ProjectVersion wiki macro throughout most of the Downloads page
  1. Change text references to the old version to refer to the new version
  2. Update the link to the NEWS file to point to the new version
  3. Update links and text to MSIs
  4. Update links and text to the main tarball
  5. Update links and text to sub tarballs, including links to news files
2. Add a new md5sum link
3. Save the page, check all links
Update PyPI records & upload files
- http://pypi.python.org/pypi/Twisted/
  - Edit the version
  - Upload tarball and MSIs
Update PyPI records, editing the version
~~Update WikiStart~~
Write the release announcement (see below)
Update ReleaseRevisions with the revision of this release
- The final revision of the release is the revision in which the release branch was made. The starting revision is the one immediately after the final revision of the previous release.
Announce the release
1. Send a text version of the announcement to: twisted-python@twistedmatrix.com, python-announce-list@python.org, python-list@python.org, twisted-web@twistedmatrix.com, twisted-jabber@ik.nu
  - Note: you need to be subscribed to some of those lists to be able to send, like twisted-jabber@….
2. Launchpad;
  - https://launchpad.net/twisted/main/+addrelease
    - Include a text version of the announcement and the new entries of the NEWS file
  - https://launchpad.net/twisted/+announcements
3. http://labs.twistedmatrix.com
  - Post a web version of the announcements, with links instead of literal URLs
4. Twitter, if you feel like it
5. #twisted topic on IRC (you'll need ops)
Merge the release branch into trunk, closing the release ticket at the same time.
- For now you need to add a .misc NEWS fragment to merge the branch.
Close the release milestone (which should have no tickets in it).
Open a milestone for the next release.

Release announcement

The final release announcement should:

Mention the version number
Include links to the release tarballs & Windows installers (both msi & exe)
Summarize the significant changes in the release
Consider including the quote of the release
Thank the contributors to the release

Here's an example:

On behalf of Twisted Matrix Laboratories, I am honored to announce the
release of Twisted $RELEASE.

Highlights include:

 * Improved documentation, including "Twisted Web in 60 seconds"

 * Faster Perspective Broker applications

 * A new Windows installer that ships without zope.interface

 * Twisted no longer supports Python 2.3

 * Over one hundred closed tickets

For more information, see the NEWS file.

It's stable, backwards compatible, well tested and in every way an
improvement. Download it now from:

 http://tmrc.mit.edu/mirror/twisted/Twisted/$API/Twisted-$RELEASE.tar.bz2 or
 http://tmrc.mit.edu/mirror/twisted/Twisted/$API/Twisted-$RELEASE.win32-py2.5.msi or
 http://tmrc.mit.edu/mirror/twisted/Twisted/$API/Twisted-$RELEASE.win32-py2.6.msi

Many thanks to Jean-Paul Calderone and Chris Armstrong, whose work on
release automation tools and answers to numerous questions made this
possible. Thanks also to the supporters of the Twisted Software
Foundation and to the many contributors for this release.

jml

When things go wrong

If you discover a showstopper bug during the release process, you have three options.

Abort the release, make a new point release (e.g. abort 10.0.0, make 10.0.1 after the bug is fixed)
Abort the release, make a new pre-release (e.g. abort 10.0.0, make 10.0.0pre3 after the bug is fixed)
Interrupt the release, fix the bug, then continue with it (e.g. release 10.0.0 with the bug fix)

If you choose the third option, then you should:

Delete the tag for the release
Recreate the tag from the release branch once the fix has been applied to that branch

Examples

Build howto documents for website

See #2380.

from twisted.python import _release as r
from twisted.python.filepath import FilePath

# Make sure to replace the following in this script:
# - the instances of $RELEASE with the version number (eg. `11.0.0`)
# - download http://bazaar.launchpad.net/~twisted-dev/twisted-website/trunk/view/head:/docs/website-template.tpl
#   somewhere and update the instance of '/path/to/website-template.tpl' accordingly

done = {}
for p in FilePath('doc').walk():
    if p.basename() == 'man':
        print 'processing manual pages:', p.path
        done[p] = True
        r.ManBuilder().build(p)

for p in FilePath('doc').walk():
    if p.basename().endswith('.xhtml'):
        if p.parent() not in done:
            print 'processing howto pages:', p.parent().path
            done[p.parent()] = True
            r.DocBuilder().build(
                '$RELEASE', FilePath('doc/core/howto'), p.parent(),
                FilePath('/path/to/website-template.tpl'),
                'http://twistedmatrix.com/documents/$RELEASE/api/%s.html',
                False)

print 'building book:'
for p in done:
    print '     ', p.path
r.BookBuilder().build(FilePath('doc/core/howto'), done.keys(),
                      FilePath('doc/core/howto/book.tex'),
                      FilePath('book.pdf'))

Open questions

How do we manage the case where there are untested builds in trunk?
Should picking a release quote be part of the release or the pre-release?
What bugs should be considered release blockers?
- Ultimately it's the RM's discretion
Should news fragments contain information about who made the changes?
A thought for future releases: since we'd really like folks to download the prereleases and try them out, perhaps we should put the [source:trunk/NEWS NEWS] file on the web somewhere official, too, so they can see all the cool stuff they can try out?
- XXX: jml doesn't know what this means any more

Bugs mentioned on this page