Making a Translate Toolkit Release¶

Get a clean checkout¶

We work from a clean checkout to ensure that everything you are adding to the build is what is in VC and doesn’t contain any of your uncommitted changes. It also ensure that someone else could replicate your process.

$ git clone git@github.com:translate/translate.git translate-release
$ cd translate-release
$ git submodule update --init

Create release notes¶

The release notes will be used in these places:

• Toolkit website - download page (used in gh-pages)
• Sourceforge download - README.rst (used to give user info)
• Email announcements - text version

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/release/$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.

Read for grammar and spelling errors.

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-

Add release notes for dev¶

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.

Up version numbers¶

Update the version number in:

• translate/__version__.py
• docs/conf.py

In __version__.py, bump the build number if anybody used the 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 toolkit user, like Pootle, to regenerate the stats and checks.

For conf.py change version and release

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.

Build the package¶

Building is the first step to testing that things work. From your clean checkout run:

$ mkvirtualenv build-ttk-release
(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.

Test install and other tests¶

The easiest way to test is in a virtualenv. You can test the installation of the new toolkit using:

$ mkvirtualenv test-ttk-release
(releasing)$ pip install path/to/dist/translate-toolkit-$version.tar.bz2

You can then proceed with other tests such as checking:

1. Documentation is available in the package

2. 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
   

3. 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.

Tag and branch 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

Publish on PyPI¶

$ ./setup.py register

To test before publishing run:

$ make test-publish-pypi

Then to actually publish:

$ make publish-pypi

Create a release on Github¶

• https://github.com/translate/translate/releases/new

You will need:

• Tarball of the release
• Release notes in Markdown

1. Draft a new release with the corresponding tag version
2. Convert the release notes to Markdown with Pandoc and add those to the release
3. Attach the tarball to the release
4. Mark it as pre-release if it’s a release candidate.

Copy files to sourceforge¶

• http://sourceforge.net/projects/translate/files/Translate%20Toolkit/

You will need:

• Tarball of the release
• Release notes in reStructured Text

These are the steps to perform:

1. Create a new folder in the Translate Toolkit release folder using the ‘Add Folder’ button. The folder must have the same name as the release version e.g. 1.10.0-rc1. Mark this as being for staging for the moment.
2. make publish-sourceforge will give you the command to upload your tarball and README.rst.
   1. Upload tarball for release.
   2. Upload release notes as README.rst.
   3. Click on the info icon for README.rst and tick “Exclude Stats” to exclude the README from stats counting.
3. Check that the README.rst for the parent Translate Toolkit folder is still appropriate, this is the text from translate/__info__.py.
4. Check all links for README.rst files, new release and parent.

Release documentation¶

We need a tagged release before we can do this. The docs are published on Read The Docs.

• https://readthedocs.org/dashboard/translate-toolkit/versions/

Use the admin pages to flag a version that should be published

Update translate website¶

We use github pages for the website. First we need to checkout the pages:

$ git checkout gh-pages

1. In _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).
2. Change $version as needed. See download.html, _config.yml and egrep -r $old_release *
3. git commit and git push – changes are quite quick, so easy to review.

Unstage on sourceforge¶

If you have created a staged release folder, then unstage it now.

Announce to the world¶

Let people know that there is a new version:

1. Announce on mailing lists: Send the announcement to the translate-announce mailing lists on translate-announce@lists.sourceforge.net
2. Adjust the #pootle channel notice. Use /topic to change the topic.
3. Email important users
4. Tweet about it
5. Update Toolkit’s Wikipedia page

Bump version to N+1-alpha1¶

Now that we’ve release lets make sure that master reflect the current state which would be {N+1}-alpha1. This prevents anyone using master being confused with a stable release and we can easily check if they are using master or stable.