These instructions are the guidelines for anyone making a Pootle commit.
We need to check and document these if needed:
We need to give localizers enough time to localize Pootle. They need time to do the actual translation and to feedback on any errors that they might encounter.
To make a new template:
make pot
And upload the templates to Pootle for translation. Update current translations against templates either on Pootle or in code and commits these updated files to Git.
Announce the new translations using these two channels:
We want to give a string freeze at least 2-4 weeks before a release. Announce that on the mailing lists.
If we do have a string freeze break then announce those to people.
A string freeze would normally run between an RC1 and a released version.
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 relicate your process.
git clone git@github.com:translate/pootle.git pootle-release
mkvirtualenv pootle-release
pip install -r requirements/build.txt
The release notes will be used in these places:
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 Pootle, which is done generically like this:
git log $version-1..HEAD > docs/release/$version.rst
Or a more specific example:
git log 2.5.0..HEAD > docs/releases/2.5.1.rst
Edit this new 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 2.5.0..HEAD --format='%aN, ' | awk '{arr[$0]++} END{for (i in arr){print arr[i], i;}}' | sort -rn | cut -d\ -f2-
The roadmap file needs to be updated. Remove things that are part of this release. Adjust any version numbering if for example we’re moving to Django 1.6 we need to change the proposed release numbers.
Look at the actual roamap commitments and change if needed. These will remain during the lifetime of this version so it is good to adjust them before we branch.
Update the version number in:
pootle/__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
Note
FIXME – We might want to automate 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
.
Update the minimum version number for the requirements in:
requirements/
pootle/depcheck.py
Update the requirements files:
make requirements
Note
I’m still not 100% why or if we need these, but until we work it out lets make sure we ship with correct files.
Update the translations from the Pootle server
Download all translations:
$ make get-translations
Update pootle/locale/LINGUAS
to list the languages we would like to
ship. While we package all PO files, this is an indication of which ones we
want packagers to use. The requirement is roughly 80% translated with no
obvious variable errors. Languages with a small userbase can be included.
$ make linguas
Check the output and make any adjustments such as adding back languages that don’t quite make the target but you wish to ship.
Build translations to check for errors:
$ make mo # Build all LINGUAS enabled languages
Building is the first step to testing that things work. From your clean checkout run:
make mo-all # if we are shipping an pre-release
make build
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 inadvertant changes make it into the release.
The easiest way to test is in a virtualenv. You can install the new toolkit using:
mkvirtualenv pootle-testing
pip install path/to/dist/Pootle-$version.tar.bz2
This will allow you test installation of the software.
You can then proceed with other tests such as checking:
Quick installation check:
pootle init
pootle setup
pootle start
# browse to localhost:8000
Documentation is available
Installation documention is correct
Meta information about the package is correct. See pypi section of reviewing meta data.
To cleanup:
deactivate
rmvirtualenv pootle-testing
You should only tag once you are happy with your release as there are some things that we can’t undo.
git tag -a 2.5.0 -m "Tag version 2.5.0"
git push --tags
If this is the final release then there should be a stable branch e.g.
stable/2.5.0
, so create one if it does not already exist.
Publish the package on the Python Package Index (PyPI)
Note
You need a username and password on https://pypi.python.org 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 a file.
It will also actually publish the meta-data so only do it when you are
actually ready.
Review the meta data. This is stored in setup.py
, use ./setup.py --help
to se some options to display meta-data. The actual long description is taken
from /README.rst
.
To test before publishing run:
make test-publish-pypi
Then to actually publish:
make publish-pypi
Publishing files to the Translate Sourceforge project.
Note
You need to have release permissions on sourceforge to perform this step.
You will need:
2.5.0-rc1
. Mark this as being for staging for the moment.make publish-sourceforge
will give you the command to upload your
tarball and README.rst
.README.rst
.README.rst
and tick “Exclude Stats” to
exlude the README from stats counting.README.rst
. Since this is generated on Sourceforge, without
reference to the docs folder, some of the links will be broken.README.rst
from Sourceforge, make
changes and upload your adjusted version. Don’t change the version in
releases/
as we want that to continue to work correctly.Pootle
folder is still
appropriate, this text is the text from /README.rst
.README.rst
files for existing releases, new
release and the parent folders.We need to allow users to report issues against the released version.
We need a tagged release or branch 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. When we have
branched the stable release we use the branch rather then the tag i.e.
stable/2.5.0
rather than 2.5.0
as that allows any fixes of
documentation for the 2.5.0
release to be immediately available.
Change all references to docs in the Pootle code to point to the branched version as apposed to the latest version.
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)
.download.html
, _config.yml
and
git grep $old_release
git commit
and git push
– changes are quite quick so easy to
review.Note
FIXME it would be great if gh-pages accepted .rst, maybe it can if we prerender just that page?
The dashboard used in Pootle’s dashboard is updated in its own project:
release/$version.html
Do a git pull
on the server to get the latest changes from the repo.
If you have created a staged release folder, then unstage it now.
Let people know that there is a new version:
/topic
to change the topic.Some possible cleanup tasks:
Pootle
top level download page.deactivate; rmvirtualenv pootle-release
master
.