Koha release tools

The release tools repository contains a collection of scripts to aid release mantainers and release managers in their tasks during their tenure in their respective roles.

Requirements

Software

The project has recently been dockerized to simplify it's use, all you need is:

• A text editor to tweak configuration files
• Docker (install instructions)

Setup

It is not a bad idea to organize your projects on a directory. For the purpose of simplifying the instructions we will pick ~/git as the place in which to put all the repository clones:

mkdir -p ~/git
export PROJECTS_DIR=~/git

• Clone the release-tools repository

cd $PROJECTS_DIR
git clone https://gitlab.com/koha-community/release-tools.git

• Clone the koha-manual repository

cd $PROJECTS_DIR
git clone https://gitlab.com/koha-community/koha-manual.git

• Copy the example configuration file and use your favourite editor to update it to reflect your own details

cp etc/user.example etc/user.yaml
vim etc/user.yaml

• Set some mandatory environment variables:

export RELEASE_TOOLS_DIR=$PROJECTS_DIR/release-tools
echo "export SYNC_REPO=$PROJECTS_DIR/koha" >> ~/.bashrc
echo "export RELEASE_TOOLS_USER_CONFIG=$RELEASE_TOOLS_DIR/etc/user.yaml" >> ~/.bashrc
echo "export KOHA_MANUAL_REPO=$PROJECTS_DIR/koha-manual" >> ~/.bashrc
echo "export PATH=\$PATH:$RELEASE_TOOLS_DIR" >> ~/.bashrc

Usage

After that setup, you should be able to run the container like this:

release-tools --shell

Note: If the above doesn't work yet, it's likely you need to re-source your shell:

source ~/.bashrc

Always pull the latest release tools image

IMPORTANT: it is recommended that you keep your local release-tools image up to date. Always check with the rest of the Release Team if you have any doubts about this.

In order to pull the latest image, you can manually run:

release-tools --pull

Scripts

The most commonly used scripts can be found within the bin/ directory, but they are generally written to be run from within your koha source clone repository.

cd /koha

bin/koha-push

Used to check for new authors and update bugzilla prior to pushing your branch.

The script should be run from within your koha source directory.

koha-push updatebz
koha-push updatebz --range HASH..HEAD
koha-push updatebz --range HASH..HEAD

Upon execution it will walk through all commits that appear in your local branch but do not yet appear upstream. It will update etc/sponsor_map.yaml (from release_tools repo) and docs/contributors.yaml (from Koha repo). The script will then mark the relevant bugs as 'Pushed to X', add the relevant version to the versions released box and add your configured thankyou comment to the bug.

bin/koha-release

Used to build the release notes and report release information.

The script should be called from within your koha source directory.

koha-release v19.11.00..HEAD info
koha-release v19.11.00..HEAD notes
koha-release v19.11.00..HEAD notes --silent
koha-release v19.11.00..HEAD html misc/release_notes/release_notes_19_11_01.html
koha-release v19.11.00..HEAD tarball --branch BRANCH

Upon execution it will walk through all commits in your given range and generate a set of release notes from their content sourcing data from the commits, bugzilla and the translation site. It will interactively ask you about author details should it find a commit with an unrecognised author, unless the --silent parameter is passed.

• The notes command will output a markdown file.
• The html command will read in the aforementioned markdown file and general an html file.
• The tarball command will produce the signed tar archives to be uploaded to download.koha-community.org

bin/koha-resync-bz

Used to resync Bugzilla with git commits for maintenance releases when Bugzilla has fallen out of sync.

The script should be run from within your koha source directory on a maintenance branch (e.g., 24.11.x).

koha-resync-bz --verbose
koha-resync-bz --execute
koha-resync-bz --tag v24.11.01 --execute

Upon execution it will:

1. Analyze git commits since the base version tag (e.g., v24.11.00)
2. Extract bug numbers from commit messages using the standard Bug XXXXX pattern
3. Map each commit to its corresponding version tag (handles vYY.MM.XX-i format)
4. Update bugs in Bugzilla that don't already have the target version:
   • Add the version to "Version(s) released in" field
   • Update status appropriately (main→stable, stable→oldstable, etc.)
   • Add comment "Pushed to X.XX.XX"

The script defaults to dry-run mode for safety. Use --execute to perform actual updates. Bugzilla credentials should be set via BZ_login and BZ_password environment variables.

bin/koha-team

Used to extract QA Team members from git commit trailers between two tags or commits.

The script should be run from within your koha source directory.

koha-team --start v23.11.00 --end v24.05.00
koha-team --start v24.05.00
koha-team --start v23.11.00 --mailmap /path/to/custom.mailmap

Upon execution it will:

1. Find all commits with "Bug NNNN" in the subject line within the specified range
2. Extract all 'Signed-off-by:' trailers from each commit
3. Take the second-to-last signoff as the QA person (assuming release manager signs last)
4. Use .mailmap to normalize email addresses and names
5. Generate a report with QA member names, commit counts, and bug numbers

The script outputs a formatted report showing QA team member names, number of bugs they signed off on, individual bug numbers (for members with fewer than 5 bugs), and total count of unique QA team members.

bin/koha-update-sponsors

Used to extract and update sponsor information from git commit trailers for display on the Koha about page.

The script should be run from within your koha source directory at release time.

koha-update-sponsors
koha-update-sponsors --verbose

Upon execution it will:

1. Extract all 'Sponsored-by:' trailers from git commit history
2. Load existing docs/sponsors.yaml to preserve historical sponsors
3. Apply alias resolution from etc/sponsor_map.yaml to consolidate duplicates
4. Merge sponsor data with location and URL information from sponsor_map
5. Generate/update docs/sponsors.yaml with consolidated sponsor list
6. Detect potential duplicate entries and suggest alias_of mappings

The script preserves historical sponsors (those without git trailers) while merging contributions from duplicate entries. Sponsor aliases should be configured in etc/sponsor_map.yaml using the alias_of field to map variant names to canonical names.

Process at Release Time:

1. Update sponsor_map.yaml in release-tools with any new sponsors or aliases
2. Run koha-update-sponsors from your koha source directory
3. Review and commit the updated docs/sponsors.yaml in Koha repo
4. Commit any changes to etc/sponsor_map.yaml in release-tools repo

The about page (about.pl and about.tt) automatically loads and displays the sponsor data with locations.