wiki:ReleaseProcess

Version 52 (modified by jml, 4 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

Overview

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

Prerequisites

To release Twisted, you will need:

  • Commit privileges to Twisted
  • Shell access to cube.twistedmatrix.com
  • Write permissions to /srv/www-data/twisted on cube (normally, www-data membership)
  • Write permissions to /srv/www-data/website/vhosts/twistedmatrix.com/documents

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

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.
  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 trunk/LICENSE, trunk/twisted/_version.py and 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
  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 labs.twistedmatrix.com

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

For the release itself

Notes

  • Test change-versions with pre-releases
  • There should be a template for release announcements
    • Pre-release announcements should include an exhortation to test
    • Release announcements should include actual NEWS summaries and maybe a pointer to the full thing
  • There are missing scripts:
    • for uploading pre-release tarballs
      • Need a standard place to upload tarballs
    • for signing tarballs
    • for uploading release tarballs
  • It would be nice if the news fragments contained information about who made the changes
  • Mine ReleaseProcedure for useful information
  • A definition or at least some examples of what bugs should be considered release blockers would be a good idea. Ultimately it's the RM's discretion though.
  • "Other fixes" and maybe all tickets should be links when they are on the web

Examples

Build API docs for website

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

APIBuilder().build(
    'Twisted', 'http://twistedmatrix.com/', 
    'http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/',
    FilePath('twisted'),
    FilePath('api'))

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
        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(
                '10.0.0', FilePath('doc/core/howto'), p.parent(),
                FilePath('doc/core/howto/template.tpl'),
                'http://twistedmatrix.com/documents/10.0.0/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'))

Twisted 10.0.0 announcement

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:

 http://tmrc.mit.edu/mirror/twisted/Twisted/10.0/Twisted-10.0.0.tar.bz2 or
 http://tmrc.mit.edu/mirror/twisted/Twisted/10.0/Twisted-10.0.0.win32-py2.5.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

Open questions

  • How do we manage the case where there are untested builds in trunk?
  • How/when in this process are the docs built?
  • When should the front page of the wiki be updated?
  • Should picking a release quote be part of the release or the pre-release
  • 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?
    • XXX: jml doesn't know what this means any more

See also