Making a Translate Toolkit Release

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.

Prepare the relese

Create release notes

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 $(git describe --tags --abbrev=0)..HEAD >> docs/releases/$version.rst

Or a more specific example:

$ git log $(git describe --tags --abbrev=0)..HEAD > docs/releases/3.6.0.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:

  1. The voice is active. ‘Translate has released a new version of the Translate Toolkit’, not ‘A new version of the Translate Toolkit was released by Translate’.

  2. The connection to the users is human not distant.

  3. We speak in familiar terms e.g. “I know you’ve been waiting for this release” instead of formal.

We create a list of contributors using this command:

$ git log $(git describe --tags --abbrev=0)..HEAD --format='%aN, ' | awk '{arr[$0]++} END{for (i in arr){print arr[i], i;}}' | sort -rn | cut -d\  -f2- >> docs/releases/$version.rst

Up version numbers

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.

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.

Publish the new release

Once the master branch is ready, the package can be published. This is automated by .github/workflows/setup.yml which automatically publishes tagged release to PyPI and GitHub.

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/2.2.x
$ git push origin stable/2.2.x
$ git tag -a 2.2.5 -m "Tag version 2.2.5"
$ git push --tags

Release documentation

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

The branches like stable/2.2.x are automatically enabled on Read the Docs using Automation Rules, so there might be nothing to do here.

Update Translate Toolkit 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 _config.yml and git grep $old_release.

  3. git commit and git push – changes are quite quick, so easy to review.

Updating release notes on Github

  1. Open GitHub release created by the GitHub Action.

  2. Edit it to include release notes (use same text as used on website).

Announce to the world

Let people know that there is a new version:

  1. Tweet about the release.

  2. Post link to release Tweet to the Translate gitter channel.

  3. Update Translate Toolkit’s Wikipedia page

Post-Releasing Tasks

These are tasks not directly related to the releasing, but that are nevertheless completely necessary.

Bump version to N+1-alpha1

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.

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.

Other possible steps

Some possible cleanup tasks:

  • Remove your translate-release checkout.

  • Update and fix these releasing notes:

    • Make sure these releasing notes are updated on master.

    • Discuss any changes that should be made or new things that could be added.

    • Add automation if you can.

We also need to check and document these if needed:

  • Change URLs to point to the correct docs: do we want to change URLs to point to the $version docs rather then latest?

  • Building on Windows, building for other Linux distros.

  • Communicating to upstream packagers.