Release maintenance

From Koha Wiki

Jump to: navigation, search
Home
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.


Contents

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 him/her 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Ā®.

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 gitmaster@git.koha-community.org:koha.git 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 gitmaster@git.koha-community.org:koha.git

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.

Releasing

Schedule

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

* 15th: string freeze
* 22nd: release

During string freeze patches that mess with strings should be avoided.

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://git.koha-community.org/release-tools.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]

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/koha-release v3.20.01..HEAD notes
 $ ~/<path_to>/release-tools/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/release_notes_3_20_01.md
- 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/release_notes_3_20_1.md
 $ git commit -m 'Update release notes for 3.20.1 release'
 $ git commit --amend -s

Push updated translation files

You need to keep in touch with the translation manager. He/she will provide you with the latest PO files. Usually in the form of a big patch against your branch. It might consist of a pull request.

If it's a big patch, you should do:

 $ git am -3 -i -u <name_of_patch_file>
 $ git commit --amend -s

If it's a pull request, the translation manager will provide a repository to make the pull. Then you should do:

 $ git fetch remotename
 $ git merge remotename/branch

Remember to sign the relevant patches.

Bump version number

For version 3.20+:

in Koha.pm

Change the following line:

 $VERSION = "3.20.00.000";

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 3.20.00.001, 3.20.00.002 and so on.

For versions 3.18.x and lower

in kohaversion.pl

Change the following line:

 our $VERSION = '3.18.07.000';

in installer/data/mysql/updatedatabase.pl

All versions:

Add this database upgrade:

$DBversion = "3.20.01.000";
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 Koha.pm kohaversion.pl installer/data/mysql/updatedatabase.pl
 $ 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.

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/roll_release.sh 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* download.koha-community.org:/home/uploads/files/

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 koha@lists.katipo.co.nz 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 similar to 'Koha 3.20.1 released'. You can do it as you wish, but I recommend using the Text editor instead of the Visual one.

Wrap the paragraphs of your release message inside

tags like this:

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

then add a More entry (that will split the announcement so it looks fine in the front page). To finish, open a <pre> tag and copy & paste the release notes from the source, ending with a closing </pre>.

Choose the right categories on the right also, for instance tick release, 3.20 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 gitmaster@git.koha-community
 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* download.koha-community.org:/home/<youruser>/
  • RMaints create drafts of the release notes on koha-community.org - 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 RM 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.

Personal tools