This page is divided in three sections. The first one lists the tasks that must be performed to get a valid package. The second section includes a list of tasks to get the package published and the release announced. The third one lists and suggests some possible cleanup tasks to be done after releasing.
Note
Please note that this is not a complete list of tasks. Please feel free to improve it.
The first steps are to create and validate a package for the next release.
We work from a clean checkout to ensure that everything you are adding to the build is what is in the repository and doesn’t contain any of your uncommitted changes. It also ensures that someone else could replicate your process.
$ git clone git@github.com:translate/translate.git translate-release
$ cd translate-release
$ git submodule update --init
Update any copyright dates in docs/conf.py:copyright
and anywhere else
that needs fixing.
$ git grep 2013 # Should pick up anything that should be examined
We create our release notes in reStructured Text, since we use that elsewhere and since it can be rendered well in some of our key sites.
First we need to create a log of changes in the Translate Toolkit, which is done generically like this:
$ git log $previous_version..HEAD > docs/releases/$version.rst
Or a more specific example:
$ git log 1.10.0..HEAD > docs/releases/1.11.0-rc1.rst
Edit this file. You can use the commits as a guide to build up the release notes. You should remove all log messages before the release.
Note
Since the release notes will be used in places that allow linking we use links within the notes. These should link back to products websites (Virtaal, Pootle, etc), references to Translate and possibly bug numbers, etc.
Read for grammar and spelling errors.
Note
When writing the notes please remember:
We create a list of contributors using this command:
$ git log 1.10.0..HEAD --format='%aN, ' | awk '{arr[$0]++} END{for (i in arr){print arr[i], i;}}' | sort -rn | cut -d\ -f2-
Update the version number in:
translate/__version__.py
docs/conf.py
In translate/__version__.py
, bump the build number if anybody used the
Translate Toolkit with the previous number, and there have been any changes to
code touching stats or quality checks. An increased build number will force a
Translate Toolkit user, like Pootle, to regenerate the stats and checks.
For docs/conf.py
change version
and release
.
Todo
FIXME - We might want to consolidate the version and release info so that we can update it in one place.
The version string should follow the pattern:
$MAJOR-$MINOR-$MICRO[-$EXTRA]
E.g.
1.10.0
0.9.1-rc1
$EXTRA
is optional but all the three others are required. The first
release of a $MINOR
version will always have a $MICRO
of .0
. So
1.10.0
and never just 1.10
.
Note
You probably will have to adjust the output of some of the functional tests, specifically the manpage ones, to use the right new version.
Building is the first step to testing that things work. From your clean checkout run:
$ mkvirtualenv build-ttk-release
(build-ttk-release)$ pip install --upgrade setuptools pip
(build-ttk-release)$ pip install -r requirements/dev.txt
(build-ttk-release)$ make build
(build-ttk-release)$ deactivate
$ rmvirtualenv build-ttk-release
This will create a tarball in dist/
which you can use for further
testing.
Note
We use a clean checkout just to make sure that no inadvertent changes make it into the release.
The easiest way to test is in a virtualenv. You can test the installation of the new release using:
$ mkvirtualenv test-ttk-release
(test-ttk-release)$ pip install --upgrade setuptools pip
(test-ttk-release)$ pip install dist/translate-toolkit-$version.tar.bz2
You can then proceed with other tests such as checking:
Documentation is available in the package
Converters and scripts are installed and run correctly:
(test-ttk-release)$ moz2po --help
(test-ttk-release)$ php2po --version
(test-ttk-release)$ deactivate
$ rmvirtualenv test-ttk-release
Meta information about the package is correct. This is stored in
setup.py
, to see some options to display meta-data use:
$ ./setup.py --help
Now you can try some options like:
$ ./setup.py --name
$ ./setup.py --version
$ ./setup.py --author
$ ./setup.py --author-email
$ ./setup.py --url
$ ./setup.py --license
$ ./setup.py --description
$ ./setup.py --long-description
$ ./setup.py --classifiers
The actual descriptions are taken from translate/__init__.py
.
Once we have a valid package it is necessary to publish it and announce the release.
You should only tag once you are happy with your release as there are some
things that we can’t undo. You can safely branch for a stable/
branch
before you tag.
$ git checkout -b stable/1.10.0
$ git push origin stable/1.10.0
$ git tag -a 1.10.0 -m "Tag version 1.10.0"
$ git push --tags
We need a tagged release before we can do this. The docs are published on Read The Docs.
Use the admin pages to flag a version that should be published.
Note
You need a username and password on Python Package Index (PyPI) and have rights to the project before you can proceed with this step.
These can be stored in $HOME/.pypirc
and will contain your username
and password. A first run of:
$ ./setup.py register
will create such file. It will also actually publish the meta-data so only do it when you are actually ready.
Run the following to publish the package on PyPI:
$ make publish-pypi
You will need:
Do the following to create the release:
We use github pages for the website. First we need to checkout the pages:
$ git checkout gh-pages
_posts/
add a new release posting. This is in Markdown format
(for now), so we need to change the release notes .rst to .md, which mostly
means changing URL links from `xxx <link>`_
to [xxx](link)
.$version
as needed. See download.html
,
_config.yml
and egrep -r $old_release *Let people know that there is a new version:
Announce on mailing lists using plain text emails using the same text (adjusting what needs to be adjusted) used for the Create a release on Github description:
Adjust the Pootle gitter channel topic. Use /topic [new topic]
to change
the topic.
Adjust the #pootle channel notice. Use /topic [new topic]
to change the
topic. It is easier if you copy the previous topic and adjust it.
Note
You might need to identify yourself by using
/msg nickserv identify [password]
so the IRC server knows you in
order to check if you have enough permissions.
Email important users
Tweet about it
These are tasks not directly related to the releasing, but that are nevertheless completely necessary.
If this new release is a stable one, bump the version in master
to
{N+1}-alpha1
. The places to be changed are the same ones listed in
Up version numbers. This prevents anyone
using master
being confused with a stable release and we can easily check
if they are using master
or stable
.
Note
You probably will have to adjust the output of some of the functional tests, specifically the manpage ones, to use the right new version.
After updating the release notes for the about to be released version, it is
necessary to add new release notes for the next release, tagged as dev
.
Some possible cleanup tasks:
translate-release
checkout.master
.We also need to check and document these if needed:
$version
docs rather then latest
?