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.
This process has only been tested on Linux or OS X, so we recommend that you do the release on Linux or OS X.
If you want to make changes to the release process, follow the normal Twisted development process (contribute release automation software that has documentation and unit tests demonstrating that it works).
By the end of a Twisted release we’ll have:
To release Twisted, you will need:
dornkirk.twistedmatrix.com as t-web#twistedTwisted 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 month of release, and mm is the number of the patch release.
For example:
Every release of Twisted includes the whole project.
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.
Incremental automatically picks the correct version number for you. Please retrieve it after you run it.
To release Twisted, we
- Get rid of any non-critical bugs
- Get any critical bugs fixed
- Check the release manager notes in case anyone has left anything which can only be done during the release.
INSTALL.rst and README.rst files to make sure things like the supported Python versions are correct
- Check the required Python version.
- Check that the list matches the current set of buildbots.
- Any mistakes should be fixed in trunk before making the release branch
- Assign it to the upcoming release milestone
- Assign it to yourself
- Call it “Release $RELEASE”
git fetch origingit checkout origin/trunkgit checkout -b release-$RELEASE-4290INSTALL.rst.python -m incremental.update Twisted --rctowncrier.LICENSE, twisted/copyright.py, and README.rst if requiredpython setup.py sdist --formats=bztar -d /tmp/twisted-release to build the tarballs.NEWS.rst to /tmp/twisted-release/ for people to view without having to download the tarballs.
(e.g. cp NEWS.rst /tmp/twisted-release/NEWS.rst)twistedmatrix.com/Releases/rc/$RELEASE (see #4353)
- You can use
rsync --rsh=ssh --partial --progress -av /tmp/twisted-release/ t-web@dornkirk.twistedmatrix.com:/srv/t-web/data/releases/rc/<RELEASE>/to do this.
- Read through the NEWS file and summarize the interesting changes for the release
- Get someone else to look over the announcement before doing it
- the twisted-python mailing list
- on IRC in the
#twistedtopic
The release candidate announcement should mention the important changes since the last release, and exhort readers to test this release candidate.
Here’s what the $RELEASErc1 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 release candidate 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
A week is a generally good length of time to wait before doing the final release.
python -m incremental.update Twisted.towncrier to make the final newsfile.README.rstgit mv docs/fun/Twisted.Quotes docs/historic/Quotes/Twisted-$API; echo '' > docs/fun/Twisted.Quotes; git add docs/fun/Twisted.QuotesREADME.rst changes.
git tag -s twisted-$RELEASE -m "Tag $RELEASE release"git push --tags
python setup.py sdist --formats=bztar -d /tmp/twisted-release
- Download the latest
.whlfiles from Buildbot and save them in the staging directory
- MD5:
md5sum Tw* | gpg -a --clearsign > /tmp/twisted-release/twisted-$RELEASE-md5sums.txt- SHA512:
shasum -a 512 Tw* | gpg -a --clearsign > /tmp/twisted-release/twisted-$RELEASE-shasums.txt- Compare these to an example of
twisted-$RELEASE-md5sums.txt- they should look the same.
- PyDoctor (from PyPI)
./bin/admin/build-docs .cp -R doc /tmp/twisted-release/
- Copy the pydoctor directory from the twisted branch into your Git checkout.
./bin/admin/build-apidocs . /tmp/twisted-release/api- Documentation will be generated in a directory called
/tmp/twisted-release/api
cd /tmp/twisted-release; tar -cvjf ../release.tar.bz2 *
cd ~; git clone https://github.com/twisted-infra/braidcd braidvirtualenv ~/dev/braid; source ~/dev/braid/bin/activate; cd ~/braid; python setup.py develop;cd ~/braid; fab config.production t-web.uploadRelease:$RELEASE,/tmp/release.tar.bz2
- Browse to
http://twistedmatrix.com/documents/$RELEASE/- Make sure that there is content in each of the directories and that it looks good
- Follow each link on the documentation page, replace current with
$RELEASE(e.g. 10.0.0) and look for any obvious breakage
fab config.production t-web.updateCurrentDocumentation:$RELEASE
- The following updates are automatic, due to the use of the ProjectVersion wiki macro throughout most of the Downloads page.
- Text references to the old version to refer to the new version
- The link to the NEWS file to point to the new version
- Links and text to the main tarball
- Add a new md5sum link
- Add a new shasum link
- Save the page, check all links
pip install -U twinetwine upload /tmp/twisted-release/Twisted-$RELEASE*
- 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
- http://labs.twistedmatrix.com (Post a web version of the announcements, with links instead of literal URLs)
- Twitter, if you feel like it
#twistedtopic on IRC (you’ll need ops)
python -m incremental Twisted --dev to add a dev0 postfix.The final release announcement should:
Here’s an example:
On behalf of Twisted Matrix Laboratories, I am honoured to announce
the release of Twisted 13.2!
The highlights of this release are:
* Twisted now includes a HostnameEndpoint implementation which uses
IPv4 and IPv6 in parallel, speeding up the connection by using
whichever connects first (the 'Happy Eyeballs'/RFC 6555 algorithm).
(#4859)
* Improved support for Cancellable Deferreds by kaizhang, our GSoC
student. (#4320, #6532, #6572, #6639)
* Improved Twisted.Mail documentation by shira, our Outreach Program
for Women intern. (#6649, #6652)
* twistd now waits for the application to start successfully before
exiting after daemonization. (#823)
* SSL server endpoint string descriptions now support the
specification of chain certificates. (#6499)
* Over 70 closed tickets since 13.1.0.
For more information, check the NEWS file (link provided below).
You can find the downloads at <https://pypi.python.org/pypi/Twisted>
(or alternatively <http://twistedmatrix.com/trac/wiki/Downloads>) .
The NEWS file is also available at
<http://twistedmatrix.com/Releases/Twisted/13.2/NEWS.txt>.
Many thanks to everyone who had a part in this release - the
supporters of the Twisted Software Foundation, the developers who
contributed code as well as documentation, and all the people building
great things with Twisted!
Twisted Regards,
HawkOwl
If you discover a showstopper bug during the release process, you have three options.
If you choose the third option, then you should:
Sometimes, bugs happen, and sometimes these are regressions in the current released version. This section goes over doing these “point” releases.
- Instead of just
--rcwhen running the change-versions script, add the patch flag, making it--patch --rc.- Instead of waiting a week, a shorter pause is acceptable for a patch release.