Version 58 (modified by Jonathan Lange, 8 years ago) (diff)


This document is a draft.

jml wrote it, and wants to give it a lot of love very very soon. If you want to edit it before then, consider talking to jml


To release Twisted, we do a pre-release and then an actual release.

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

  • Tarballs for Twisted as a whole, and for each of its subprojects
  • Windows installers for the whole Twisted project
  • Updated documentation (API, howtos & book) on the site
  • Updated download links on the site
  • Announcement emails sent to major Python lists
  • Announcement post on
  • A tag in our Subversion repository marking the release


To release Twisted, you will need:

  • Commit privileges to Twisted
  • Shell access to
  • Write permissions to /srv/www-data/twisted on cube (normally, www-data membership)
  • Write permissions to /srv/www-data/website/vhosts/
  • Channel operator permissions for #twisted
  • Admin privileges for Twisted's PyPI packages
  • Membership of
  • Contributor status for

Version numbers

Twisted releases use a time-based numbering scheme. Releases versions like, 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 subprojects. Each of these has the same number.

How to do a pre-release

  1. Check the milestone for the upcoming release
    1. Get rid of any non-critical bugs
    2. Get any critical bugs fixed
  2. Check for any regressions
  3. 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
  4. Choose a version number. Remember to include the 'preN' suffix
  5. File a ticket
    1. Assign it to the upcoming release milestone
    2. Assign it to yourself
    3. Call it "Release <version-number>"
  6. Check buildbot to make sure all supported platforms are green (wait for pending builds if necessary).
  7. Make a branch (e.g. mkbranch Twisted release-4290)
  8. Run ./bin/admin/change-versions XX.YY.ZZpreN
  9. Commit the changes made by change-versions
  10. Run ./bin/admin/build-news .
  11. Commit the changes made by build-news
  12. Bump copyright dates in [source:trunk/LICENSE], [source:trunk/twisted/] and [source:trunk/README]
  13. Make a temporary directory for the tarballs to live in (e.g. mkdir /tmp/twisted-release)
  14. Run ./bin/admin/build-tarballs . /tmp/twisted-release/
  15. Upload the tarballs to a public website (see #4353)
  16. 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
  17. Announce the pre-release on
    1. the twisted-python mailing list
    2. on IRC in the #twisted topic
    3. in a blog post, ideally

Pre-release announcment

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 10.0.0pre1 release annoucement ought to have looked like:

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

Tarballs for the first Twisted 10.0.0 pre-release are now available at:

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.


How to release Twisted

  1. Remove the 'pre' from all files that mention it (see #4316)
    1. e.g. find . -type f -not -path '*.svn*' -not -name '*~' | xargs grep -n 'pre1' to find all files
  2. Add the quote of the release to the README
  3. Submit the ticket for review
  4. When the ticket is reviewed, merge the branch into trunk
  5. Tag the release
    1. e.g. svn cp svn+ssh:// svn+ssh://
  6. Create a new staging area for the release (e.g. mkdir /tmp/twisted-release)
  7. Run ./bin/admin/build-tarballs . /tmp/twisted-release/
  8. Build windows installers
    3. For "Branch" specify the tag, e.g. "tags/releases/twisted-10.0.0"
    4. Download the latest .msi files from from, save them in the staging directory
  9. Sign the tarballs and Windows installers
    1. e.g. md5sum Tw* | gpg -a --clearsign > twisted-10.0.0-md5sums.txt
    2. e.g. scp twisted-10.0.0-md5sums.txt
    3. example of the result
  10. Upload to the official upload locations (see #2888)
    1. e.g. scp /tmp/twisted-release/Twisted-10.0.0.tar.bz2 cube:/srv/www-data/twisted/Releases/Twisted/10.0/
    2. For all subprojects, upload the tarballs to cube:/srv/www-data/twisted/Releases/<Project>/<First two parts of version number>/
    3. Windows installers go in the Twisted project
  11. 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. find /srv/www-data/twisted/Releases -name '*10.0.0*' | xargs chmod g+w
  12. Wait for the tarballs to be mirrored to tmrc
    • They are mirrored 15 minutes every hour
    • You can ask foom on #twisted to force the mirror
  13. Update the WikiStart and Downloads pages
    1. XXX: Describe this process exactly
  14. Update website documentation
    • See APIDocs
    • Get the dependencies
      • Twisted (export from tagged release branch)
      • Pydoctor
      • Nevow
      • Epytext
    • Run the unofficial build-docs script (see below)
    • Update the permissions
      • XXX: how?
    • cp the documents to /srv/.../documentation/10.0.0
      • XXX: full path please
    • rm -rf twisted/{vfs,web2} from the export
    • Run the unofficial build-api script (see below)
    • Move the API docs and update the permissions
      • cd /srv/www-data/website/vhosts/
      • mv ~exarkun/documentation/twisted-10.0.0/api/ ./10.0.0/
      • chown -R www-data.www-data 10.0.0/api/
    • Copy the book
    • Check the permissions
      • XXX: what permissions?
    • Test the generated docs
      • XXX: what to look for?
    • Change the "current" symlink
      • XXX: exact commands
    • Removing the staging area
  15. Write the release announcement (see below)
  16. Update ReleaseRevisions with the revision of this release
    • XXX: What revision exactly?
  17. Announce the release
    1. Send a text version of the announcement to: twisted-python@…, python-announce-list@…, python-list@…, twisted-web@…, twisted-jabber@…
    2. Update PyPI records
    3. Launchpad;
      • Include a text version of the announcement and the new entries of the NEWS file
      • Post a web version of the announcements, with links instead of literal URLs
    5. Twitter, if you feel like it
    6. #twisted topic on IRC (you'll need ops)

Release announcement

The final release announcement should:

  • Mention the version number
  • Include links to the release tarballs & Windows installers
  • 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 10.0.

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

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.


When things go wrong

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

  1. Abort the release, make a new point release (e.g. abort 10.0.0, make 10.0.1 after the bug is fixed)
  2. Abort the release, make a new pre-release (e.g. abort 10.0.0, make 10.0.0pre3 after the bug is fixed)
  3. 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:

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


Build API docs for website

See also APIDocs

from twisted.python._release import APIBuilder
from twisted.python.filepath import FilePath

    'Twisted', '', 

Build howto documents for website

from twisted.python import _release as r
from twisted.python.filepath import FilePath
done = {}
for p in FilePath('doc').walk():
    if p.basename() == 'man':
        print 'processing manual pages:', p.path
        done[p] = True
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
                '10.0.0', FilePath('doc/core/howto'), p.parent(),

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

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?
  • Does this document miss anything relevant that ReleaseProcedure includes?
  • 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

See also