Versioning and releases - Kee browser extension

Kee browser extension
1

This document describes how and when new versions of the Kee desktop browser extension are released and how they are assigned a version number.

Note that this information does not apply to the versioning scheme for the KeePassRPC KeePass plugin that Kee communicates with. Assume that all versions of KeePassRPC since (and including) 1.7.3 are compatible with all versions of Kee. Kee will notify you if KeePassRPC needs to be upgraded.

Release categories

There are three categories of Kee release: Stable, beta and pre-release.

  • Stable releases are the ones that are made publicly available on your web browser’s addon store (e.g. https://addons.mozilla.org for Firefox or https://chrome.google.com/webstore for Chrome)
  • Beta versions are made available via the Beta channel for Firefox users, hosted on GitHub (latest Beta version)
  • Pre-release versions are only available via the GitHub Releases page
  • Versions that are tagged with a green “release” (or “latest release”) on GitHub have been released as a beta version and sometimes also a stable version. Delays by Mozilla, Google and other browser creators can mean that these releases are not available for you immediately.
  • Note that stable releases may sometimes be marked as “pre-release” on GitHub, although the description of the release will make it clear if the build was used as a stable release for all users.

Version numbers

Each Kee release is assigned a version number containing 3 components:

  • major - Significant feature changes, potentially breaking backwards compatibility. It is important to always read release notes for versions with a higher version number and it should not be assumed that rolling back to a lower major version will be successful.
  • minor - regular feature additions and changes, with a very low chance of backwards compatibility problems.
  • patch - Every build of Kee receives a new patch number. For beta and stable versions, you can assume only minor adjustments to features or security fixes. For pre-release versions, assume nothing because the build may be an entirely automated snapshot of experimental work - while often insignificant, such changes could occasionally be highly disruptive and could slightly predate the incrementation of a minor or major version number.

These components are listed from left to right. So, for example, version 2.3.4 is major version 2, minor version 3 and patch version 4.

Occasionally a 4th number will be included - for example 2.3.19.1. This build number indicates a rebuild or repackaging operation and indicates no modifications to the addon code, indeed you often will not even find a corresponding release on GitHub since it is identical to its base version in all meaningful ways (2.3.19 in this example). Reasons for this typically involve working around limitations of delivery platforms such as Mozilla’s add-ons website.

Automated GitHub releases

Every change on the main (“master”) code branch on GitHub is automatically built and assigned a new version number. Only the patch number will be incremented automatically - major and minor are always incremented manually when applicable.

The files generated as part of this build are not signed by Mozilla (Firefox) or Google (Chrome) so can only be installed using those browser’s respective development mode features. Instructions for doing this tend to vary so please consult the browser’s documentation to work out which browser version and configuration steps are required to load these builds. In case it needs spelling out, caveat emptor when it comes to using experimental builds. No automatic updates will be offered for these builds.

Release process

Releases will be made from builds generated by GitHub Actions on a release/<major>.<minor> branch.

In most cases, the only differences between the packages created on the release branch and the branch base commit on master will be non-English translations but occasional critical fixes may be added too.

The existence of a release branch does not guarantee that the version will be released. In some cases we may elect to skip publishing the release and instead focus on the next release. This decision may be taken before or after the beta release from a release branch.

The following commands are a record of the evolving process that luckyrat will perform during the release process. In theory other collaborators could also perform some of this but at the moment only luckyrat has the necessary credentials to deliver a release into user’s hands so that’s not useful in practice.

# Create a release branch:
RELEASE_VERSION_MAJ_MIN=3.10 && NEXT_VERSION_MAJ_MIN=3.11 && git checkout master && git pull && git checkout -b release/$RELEASE_VERSION_MAJ_MIN && git push --set-upstream origin release/$RELEASE_VERSION_MAJ_MIN && git checkout - && sed -E 's/^(.*"version": ")(.*)("\,.*)/\1'${NEXT_VERSION_MAJ_MIN}.0'\3/' package.json > package.json.tmp && mv package.json.tmp package.json && git add -A && git commit -m "Bump version to ${NEXT_VERSION_MAJ_MIN}" && git push

# Add translations to release branch
RELEASE_VERSION_MAJ_MIN=2.3 && git fetch && git checkout release/$RELEASE_VERSION_MAJ_MIN && tx pull -a -f --minimum-perc=50 && git add -A && git commit -m "Updated translations" && git push

# copy recent commits from release branch onto master
# In this case we take the one latest commit but sometimes will need more
RELEASE_VERSION_MAJ_MIN=3.0 && git fetch && git checkout release/$RELEASE_VERSION_MAJ_MIN && git rebase --onto master HEAD~1 HEAD
# if changes have been made to master in the mean time, merge
# conflicts may need to be resolved.
# If this rebase command selects commits that were already included on
# master, either interactively skip them or run `git reset` and
# `git rebase --continue` when an empty commit is found.
git rebase HEAD master
git push

Beta release process

The builds generated on the release branches need to be published as a beta testing version before we can publish a stable version. As a result of changes to Mozilla’s behaviour and version string requirements in recent years, we can no longer automate this process. The process described below is our first attempt at manually performing these chores.

  1. Once automated release build on GitHub has finished, download the source zip file from the release page.
  2. Upload the source zip to the newly created version page on AMO.
  3. Wait.
  4. After Mozilla provide the signed XPI…
  5. Load Mozilla accounts
  6. Load the relevant “self” version page
  7. Save the XPI from the Files section of that page to the kee-firefox-beta-release-management/signed-xpis/<NEW_KEE_VERSION>/ folder (create the new folder first)
  8. Run code below and upload resulting XPI to the GitHub release page
cd kee-firefox-beta-release-management

export NEW_KEE_VERSION=<NEW_KEE_VERSION>

# git clone browser-addon-updates # (if not already done on this device)

# Get the sha256 checksum for this release:
sha256sum signed-xpis/${NEW_KEE_VERSION}/keefox-${NEW_KEE_VERSION}-beta.xpi

cd browser-addon-updates

# Edit the update.json file:
# 1. Copy/paste to duplicate the most recent entry
# 2. Edit the version number in the 3 locations
# 3. Replace the sha checksum with the newly calculated one
# 4. Update strict_min_version if required

git add . && git commit -m "Manual release of beta version ${NEW_KEE_VERSION}" && git push
1 Like