Context Navigation

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.

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.

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

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

e.g. md5sum Tw* | gpg -a --clearsign > twisted-$RELEASE-md5sums.txt

e.g. scp twisted-$RELEASE-md5sums.txt cube.twistedmatrix.com:/srv/www-data/twisted/Releases/ (XXX This will automatically adjust the links on the Downloads page, even though the release files are not yet in place. Consider moving this step to a later part of the process.)

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

Open questions

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 NEWS​ file on the web somewhere official, too, so they can see all the cool stuff they can try out?