Release maintenance

From Koha Wiki

Jump to: navigation, search
Koha > Technical > Development
Koha > Technical > Development > Release Management

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, Chris Nighswonger and Firdolin Somers 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).

MRenvoize uses a quick and dirty script to add bugs from master into hist todoist list.

You should also watch Bug 17108 - Automatic debian/control updates for patches specific to your version as they may well not hit master ;)

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 by changing the status to Pushed to Stable/oldstable/oldoldstable and we also now have a custom field (Version(s) released in:) in bugzilla which you should add the specific release version to for which the bug will be released (This field takes the form of a comma delimited list of versions, for example `19.05.00, 18.11.03, 18.05.11`).


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

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
 junitmsgfmt misc/translator/po/*

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

You will also need to check for possible XSS attempts:

 The POs must *not* contain:
 % git grep '<script' **/*.po
 % git grep PERL **/*.po # This has 4 occurrences, but not valid

Bump version number

In increment the following line:


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.

Add this database upgrade:

$DBversion = "YY.MM.XX.XXX";
if ( CheckVersion($DBversion) ) {
    print "Upgrade to $DBversion done (YY.MM.XX release)\n";
    SetVersion ($DBversion);

You should then commit those changes:

 $ git add installer/data/mysql/
 $ git commit -m 'Increment version for YY.MM.XX release'
 $ git commit --amend -s

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

Generate the release notes

NOTE: Make sure to pull the latest version of the release tools before generating the notes

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

 $ ~/<path_to>/release-tools/bin/koha-release v17.05.00..HEAD notes
 $ ~/<path_to>/release-tools/bin/koha-release v17.05.00..HEAD html misc/release_notes/release_notes_17_05_01.html

it will create the following files:

- misc/release_notes/
- misc/release_notes/release_notes_17_05_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:

 $ git add misc/release_notes/ misc/release_notes/release_notes_17_05_01.html
 $ git commit -m 'Update release notes for 17.05.01 release'
 $ git commit --amend -s

It's not a bad idea at this point to push your branch upstream one last time and watching all the tests pass before tagging it for release.

Tag the release

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

 $ git tag -a v17.05.01 -s -m 'Koha release 17.05.01'

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

 $ git push koha_git_master v17.05.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/ 17.05.01 local_release_branch

It will create the following files under the releases dir:

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

You then have to upload the generated files for distribution:

 $ scp releases/koha-17.05.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.

Update bugzilla

Skip this step for now, it warrants further discussion

Bugs included in this release should now be marked as RESOLVED FIXED as part of the release procedures.

The simplest way to achieve this is to use the koha-release script after release:

 $ ~/<path_to>/release-tools/bin/koha-release v17.05.00..HEAD updatebz

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 17.05.01 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 YY.MM.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 17.05.01.
  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 17.05.XX 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-17.05.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.

Tips and Tools

  • One can use a slightly adapted version of the release manager pre-push hook to check your work before pushing to your maintenance branch: hook
  • I use the follow git post-commit hook as a simple way to track whether a fix I've backported has introduced a new author that should be added to the history.txt file and about page.

AUTHOR="$(git log -1 --pretty=format:'%an' HEAD)"

if grep -q "${AUTHOR}" ${FILE}; then
 tput setaf 2; echo "Existing Author: \"${AUTHOR}\""; tput sgr0;
 tput setaf 1; echo "New Author: \"${AUTHOR}\""; tput sgr0;

Personal tools