The process of a new release starts with the creation of a new release development branch.
A release development branch is the one that will be stabilized and eventually become the actual
released version. Release branches are always named dev-vM.m, after the
major and minor versions they include. Major and minor versions are
always branched from master. When the release is actually published a patch version number is added
and the release is tagged in the form ckan-M.m.p. All backports are cherry-picked on the dev-vM.m branch.

Additionally, the release-vM.m-latest branches always contain the latest
published release for that version (eg 2.6.1 on the example above).

Note

Prior to CKAN 2.6, release branches were named release-vM.m.p, after the
major, minor and patch versions they included, and patch releases
were always branched from the most recent tip of the previous patch release branch
(tags were created with the same convention).
Starting from CKAN 2.6, the convention is the one described above.

Once a release branch has been created there is generally a three-four week period until
the actual release. During this period the branch is tested and fixes cherry-picked. The whole
process is described in the following sections.

Update ckan/__init__.py to change the version number to the new version
with a b after it, e.g. 2.7.0b (Make sure to include 0 as the patch version number).
Commit the change and push the new branch to GitHub:

git commit -am "Update version number"
git push origin dev-v2.7

You will probably need to update the same file on master to increase the
version number, in this case ending with an a (for alpha).

During the beta process, all changes to the release branch must be
cherry-picked from master (or merged from special branches based on the
release branch if the original branch was not compatible).

As in the master branch, if some commits involving CSS changes are
cherry-picked from master, the less compiling command needs to be run on
the release branch. This will update the main.css file:

./bin/less --production
git commit -am "Rebuild CSS"
git push

There will be a final front-end build before the actual release.

Update beta.ckan.org to run new branch.

The beta staging site
(http://beta.ckan.org, currently on s084) must be set to track the latest beta
release branch to allow user testing. This site is automatically updated nightly.

Extract new strings from the CKAN source code into the ckan.pot
file. The pot file is a text file that contains the original,
untranslated strings extracted from the CKAN source code.:

python setup.py extract_messages

The po files are text files, one for each language CKAN is translated to,
that contain the translated strings next to the originals. Translators edit
the po files (on Transifex) to update the translations. We never edit the
po files locally.

Get the latest translations (of the previous CKAN release) from
Transifex, in case any have changed since:

tx pull --all --minimum-perc=5 --force

(This ignores any language files which less than 5% translation - which
is the bare minimum we require)

Update the ckan.po files with the new strings from the ckan.pot file:

python setup.py update_catalog --no-fuzzy-matching

Any new or updated strings from the CKAN source code will get into the po
files, and any strings in the po files that no longer exist in the source
code will be deleted (along with their translations).

We use the --no-fuzzy-matching option because fuzzy matching often
causes problems with Babel and Transifex.

If you get this error for a new translation:

babel.core.UnknownLocaleError: unknown locale ‘crh’

then it’s Transifex appears to know about new languages before Babel
does. Just delete that translation locally - it may be ok with a newer Babel in
later CKAN releases.

Run msgfmt checks:

find ckan/i18n/ -name "*.po"| xargs -n 1 msgfmt -c

You must correct any errors or you will not be able to send these to Transifex.

A common problem is that Transifex adds to the end of a po file as
comments any extra strings it has, but msgfmt doesn’t understand them. Just
delete these lines.

Run our script that checks for mistakes in the ckan.po files:

paster check-po-files ckan/i18n/*/LC_MESSAGES/ckan.po

If the script finds any mistakes then at some point before release you
will need to correct them, but it doesn’t need to be done now, since the priority
is to announce the call for translations.

When it is done, you must do the correction on Transifex and then run
the tx pull command again, don’t edit the files directly. Repeat until the
script finds no mistakes.

Edit .tx/config, on line 4 to set the Transifex ‘resource’ to the new
major release name (if different), using dashes instead of dots.
For instance v2.4.0, v2.4.1 and v2.4.2 all share: [ckan.2-4].

Create a new resource in the CKAN project on Transifex by pushing the new
pot and po files:

tx push --source --translations --force

Because it reads the new version number in the .tx/config file, tx will
create a new resource on Transifex rather than updating an existing
resource (updating an existing resource, especially with the --force
option, can result in translations being deleted from Transifex).

If you get a ‘msgfmt’ error, go back to the step where msgfmt is run.

On Transifex give the new resource a more friendly name. Go to the
resource e.g. https://www.transifex.com/okfn/ckan/2-5/ and the settings are
accessed from the triple dot icon ”...”. Keep the slug like “2-4”, but change
the name to be like “CKAN 2.5”.

Update the ckan.mo files by compiling the po files:

python setup.py compile_catalog

The mo files are the files that CKAN actually reads when displaying
strings to the user.

Send an email to the ckan-dev list, tweet from @CKANproject and send a
transifex announcement from: https://www.transifex.com/okfn/ckan/announcements/
. Make sure to post a link to the correct Transifex resource (like this one) and tell users that they can
register on Transifex to contribute. Give a deadline in two weeks time.

Create deb packages.

Ideally do this once a week. Create the deb package with the latest release
branch, using betaX iterations. Deb packages are built using Ansible
scripts located at the following repo:

The repository contains further instructions on how to run the scripts, but
essentially you need to generate the packages (one for precise and one for
trusty) on your local machine and upload them to the Amazon S3 bucket.

We don’t generally merge or cherry-pick release branches into master, but
the files in ckan/i18n are an exception. These files are only ever changed
on release branches following the Doing the beta release instructions above,
and after a release has been finalized the changes need to be cherry-picked
onto master.

To find out what i18n commits there are on the release-v* branch that are
not on master, do:

git log master..dev-v* ckan/i18n

Then checkout the master branch, do a gitstatus and a gitpull
to make sure you have the latest commits on master and no local changes.
Then use gitcherry-pick when on the master branch to cherry-pick these
commits onto master. You should not get any merge conflicts. Run the
check-po-files command again just to be safe, it should not report any
problems. Run CKAN’s tests, again just to be safe. Then do gitpushoriginmaster.

Announce the release date & time with a week’s notice on ckan-announce.

Often this will be part of the announcement of a CKAN major/minor release.
But if patches go out separately then they will need their own announcement.

Update ckan/__init__.py with the incremented patch number e.g. 2.5.1 becomes 2.5.2.
Commit the change and push the new branch to GitHub:

git commit -am "Update version number"
git push origin release-v2.5.2

Cherry-pick PRs marked for back-port.

These are usually marked on Github using the BackportPendinglabels and the
relevant labels for the versions they should be cherry-picked to (eg Backport2.5.3).
Remember to look for PRs that are closed i.e. merged. Remove the BackportPending label once the
cherry-picking has been done (but leave the version ones).

Ask the tech team if there are security fixes or other fixes to include.