Release maintenance

From Koha Wiki

Jump to: navigation, search
Koha > Technical > Development

Note: this guidelines are work in progress, and release maintainers have the right to change this to whatever they prefer. For now this will serve as a documentation place for the tasks involved in release maintenance.


The Release Maintainer role

Release maintainers do the task of keeping the stable Koha releases in line with patches provided for bugfixes. People are elected for this task after they volunteered for it, and there is consensus on the develpement community for them to take on the job.

RMaint people are assigned one or more stable branches to maintain. Crazy people like Chris Cormack and Chris Nighswonger have maintained more than one release at a time. Its a crazy Chris thingĀ®.


Every month there is a stable maintainance release. The relevant dates are:

  • 15th: String Freeze
  • 22nd: Release

String Freeze: During String Freeze patches that change strings should not be pushed! Please keep in mind that a changed string will mean that the string appears untranslated after updating, which can be especially toublesome for OPAC strings. Most users rely on the packages to provide translations and are not aware how they could fix such problems locally.

  • Get in touch with the translation manager on time to have them update the po files on
  • Announce String Freeze on the koha-translate mailing list

Release: After each release, get in touch with your fellow release maintainers and the packaging manager in order to agree about a date for string freeze, a date for when your branches will all be ready for packaging and a date for the release. This is thought to make the life of our packaging manager easier as they can build all branches at once. Also it means that the packages will be ready at release.

Daily maintenance workflow

RMaint people usually watch the activity on the master git branch. If they maintain a release other than the latest stable release, they should be looking at higher numbered versions git logs (for example, if you are maintaining the 3.10.x stable branch, then you should be probably watching 3.12.x's, and keep in touch with its maintainer).

You could set an RSS/Atom feed reader to keep you up to date. As soon as I find a tool that fits for me, I'll update this page. Its been said that tt-rss has tagging capabilities, so it looks promising.

Take on a commit or commit series

Once you spot a specific commit or commit series on your queue, the first thing is to look at bugzilla and check if it is a bugfix or an enhancement. If its the latter, you should dig a bit more on it to make a decision. It is a common practice to check with the rest of the devs on IRC or mailing the author of the patches for clarification.

You should be particularly cautious about backporting a change that includes a database update. This is because a library that uses your stable branch will eventually upgrade to a newer major release, and as a consequence may run the same DB revision. In order to avoid surprises, you should only backport DB changes that can safely be run repeatedly. For example, an 'ALTER TABLE foo MODIFY COLUMN...' that just changes the type of a column will usually be idempotent. A DB update that deletes (for example) useless data will typically be idempotent. However, a DB update that adds a new table will result in a warning, at least, during upgrade, and should be avoided unless it is absolutely required in order to resolve a security bug. When it doubt, please discuss with the RM and your fellow RMaints first.

Once you decided the patch should be backported to the stable branch you are maintaining, update your local git repository (just in case) and create a working branch. You should define a naming schema to avoid confusion now you have commit rights! As 3.12.x release maintainer I chose 312_cp_<bugnumber>. Do what you want :-D

git checkout origin/3.20.x -b 320_cp_<bugnumber>

You should then look for the commit hash of the patch(es). And then cherry-pick them like this:

git cherry-pick -x 1a8db0ba7d62a70cd6b49ee705a5db9b11ad7672

If there's some conflict with cherry-picking, git will tell you. You will have two options

  • Solve the conflict
  • Try to solve the conflict and give up

If solving the conflict is not straightforward, comment on the bug like this: 'This does not apply cleanly to 3.20.x please submit one formatted for 3.20.x'.

If you solved the conflict you finish by

git add <touched files>
git commit

A cherry-pick message is added to the commit, and if there where conflicts, on which files.

You should run some tests. For example, if the patch modifies several templates, you should at least run:

perl xt/tt_valid.t
perl xt/author/valid-templates.t

Do some testing, and keep in mind you should be confident about the QA team.

Once everything is solved, and testing proves everything is fine with the cherry-picked commits, you should sign on them:

git commit --amend -s

And then push the changes

git push 320_cp_<bugnumber>:3.20.x

Create a remote for pushing

You could also set a remote for pushing like this:

git remote add koha_gitmaster

and then push using this shorter version:

git push koha_gitmaster 320_cp_<bugnumber>:3.20.x

Update Bugzilla

This is very important: let people know you pushed the patches to your stable branch. Add a comment on the relevant bugs like this 'This patch has been pushed to 3.20.x, will be in 3.20.1.' and change the status to Pushed to Stable.


Release tools

This section lists the set of tools a release maintainer needs to be set to do the job.

The release-tools repo

The Koha dev community has a nice set of tools to make the job easier. This set of scripts is on a git repo that can be cloned using

 $ git clone git://

GPG keys

In order to sign the git version tag you need to have valid gpg signatures. Generate them issuing:

 $ gpg --gen-key

Keys can be generated using 4096 or 2048 bits. It took me a while and lots of USB HDD activity to get enough entropy but I managed to generate it with 4096 bits.

You may need to configure your git repo, see here.

You can add the key quickly to a repo (or all repos) with

$ git config --global user.signingkey [gpg-key-id]

Push updated translation files

Keep in touch with the translation manager to get the strings on updated in time for String Freeze on the 15th of a month.

Right before release, you can use a form provided by the translation manager, to automatically create a new branch on the TM's git repository with the latest version of the po files. Note: As the form is not protected at the moment, you can get the link to it from one of the previous Release Maintainers.

You will receive an email with all necessary information about the created branch and can then merge it into yours:

 $ git fetch remotename
 $ git merge remotename/branch

Remember to sign the relevant patches.

If you want to check the po files for errors, you can do:

 sudo apt-get install translate-toolkit package, 
 junitmsgfmt misc/translator/po/ar-Arab-staff-prog.po
 junitmsgfmt misc/translator/po/*

An error can be fixed, for example, by marking the string as 'fuzzy' in the po file.

Bump version number

For version 3.20+:


Change the following line:

 $VERSION = "";

Remember that between releases there might be minor database version upgrades. They would have been done the same way, using the latest minor number to reflect those version changes. For example, and so on.

For versions 3.18.x and lower


Change the following line:

 our $VERSION = '';

in installer/data/mysql/

All versions:

Add this database upgrade:

$DBversion = "";
if ( CheckVersion($DBversion) ) {
    print "Upgrade to $DBversion done (3.20.1 release)\n";
    SetVersion ($DBversion);

You should then commit those changes (files depending on version):

 $ git add installer/data/mysql/
 $ git commit -m 'Increment version for 3.20.1 release'
 $ git commit --amend -s

You can now push the latest changes. Or continue with the next step.

Generate the release notes

Release notes are automatically generated by the koha-release script from the release-tools repo. If you are releasing version 3.20.1 you should run this on your clean 3.20.x branch:

 $ ~/<path_to>/release-tools/bin/koha-release v3.20.01..HEAD notes
 $ ~/<path_to>/release-tools/bin/koha-release v3.20.01..HEAD html misc/release_notes/release_notes_3_20_01.html

it will create the following files:

- misc/release_notes/
- misc/release_notes/release_notes_3_20_01.html

It is important that you edit that file and fix any inconsistency you find. Usually

- If there are no features/enhancements/bugfixes the current script generates empty sections for them.
- The branch name might be wrong at the end of the file.

Just make sure everything is sound. Once you are done, you should commit the release notes (note we are only adding the text version):

 $ git add misc/release_notes/
 $ git commit -m 'Update release notes for 3.20.1 release'
 $ git commit --amend -s

Tag the release

Tagging will prompt for your GPG passphrase. It is done issuing:

 $ git tag -a v3.20.01 -s -m 'Koha release 3.20.01'

Note the two digits. You can now push the new tag doing:

 $ git push koha_git_master v3.20.01

Roll the release

This step creates the release tarball. It needs the release-tools repo. You have to run

 $ mkdir releases
 $ ~/path-to/release-tools/ 3.20.01 local_release_branch

It will create the following files under the releases dir:

  • koha-3.20.01.tar.gz
  • koha-3.20.01.tar.gz.MD5
  • koha-3.20.01.tar.gz.MD5.asc
  • koha-3.20.01.tar.gz.sig

You then have to upload the generated files for distribution:

 $ scp releases/koha-3.20.01.tar.gz*

Then log into the server.

Older versions of the same release should be moved into the old_releases directory.

If you create latest stable release, recreate symlink koha-latest.tar.gz.

Public announcement

People should know there's a new Koha release. We announce it by email and posting it on the Koha Community site.

Email announcement

Email announcements are sent to the user list with a subject that should read like 'Koha 3.20.1 released'.

Note: keep in mind that the release announcement will be more than 40k and will be subject to moderation. So, be patient :-D

Post on the community site

The current community site is a Wordpress site. You should have a valid credentials and create a new Post. It should be titled 'Koha XX.XX.XX released'. We recommend using the Text editor instead of the Visual one. You can copy the HTML source code of the generated release notes into the Text editor with very few changes necessary:

Just change the first paragraphs of the generated release notes a bit, for example:

  The Koha community is proud to announce the release of 3.20.1.
  This is a maintenance release and contains many bugfixes and
  As always you can download the release from:
  This is my first release as the 3.20.x release maintainer.
  Thank you very much to everyone involved in this release.

then add a More entry (that will split the announcement so it looks fine in the front page).

Choose the right categories: release, <your branch> and Announcements.

And that's it :-D.

Coordinated security releases

Sometimes it will be necessary to do a coordinated release of all maintained versions at the same time because of security related fixes. This is the workflow:

  • RM initiates a security release by emailing the RMaints and the Packaging Manager and provide them with the necessary information, like a list of bugs to push.
  • RMaints push the patches from Bugzilla to the protected security repository. They don't push to their normal branches until some time after release.
 git remote add security
 git push security HEAD:new/security-release-foo
  • RMaints generate the release notes as usual. As the security bugs are not accessible from the outside, they need then to be added to the generated notes manually.
  • RMaints roll tarballs and upload them to their non-public home directory on the download server:
 $ scp releases/koha-3.20.01.tar.gz*<youruser>/
  • RMaints create drafts of the release notes on - unpublished, but ready for publishing.
  • Once an RMaint has finished those steps, they will inform the others.
  • The Packaging Manager will build the packages from the security repository.
  • The RMaint of the most recent release (RMaint1) coordinates the last steps with the Packaging Manager. He then moves the tarballs into the public directory, publishes the drafts on the website and sends an email announcing the security releases to the mailing lists.
  • The RMaint1 changes the bug status from security project to Koha project after pushing to master.
  • RMaints change the bug status and add comments after that.
Personal tools