Skip to content

Release workflow

Jump to bottom
Marc Durdin edited this page May 15, 2024 · 51 revisions

Alpha/nightly

While we are doing active development on a product, every evening we have an alpha master/nightly build. The nightly build simply takes the last successful alpha master build and publishes it to downloads.keyman.com as "alpha".

Acceptance Test

Before transitioning to beta or stable phase and announcing, an acceptance test must be performed according to the documented protocol for the platform. The protocol will be documented on this wiki.

When going into beta, make sure that the checklist in the Wiki is updated to reflect recent feature changes.

Moving to beta

At a certain point, we will declare the alpha/nightly build to be approaching stability. At that point, we will fork to a new branch, e.g. beta. At the same time, the minor version number on the master build will be incremented (or major number if we are doing a major increment), and the build number will be reset on master. Typically no new features will be accepted into the release branch, just bug fixes, but multiple betas may be released. The branch will fork again to stable-10.0. After the fork to stable, the beta branch can be deleted, as no further work can be done in beta for that release.

Note for Android: In the Google Play Store console, deactivate the list of closed-alpha testers, leaving only the Placeholder list. This way, Beta testers will not be served alpha versions during the beta phase.

Beta Steps

The steps to move to beta, then, are:

  1. Make sure the master branch is clean, up to date and ready to go (ideally all pull requests merged, etc). Make sure that the latest nightly is tested and working to an appropriate level.

  2. Ensure the changelog (/HISTORY.md) has all relevant change information for beta and stable.

  3. Freeze master branch so no one pushes to it (freeze can be either through technology or by communicating this to the team).

  4. Run the user test protocol against the master branch.

  5. Delete the existing beta branch on keymanapp/keyman repo (including unprotecting it as necessary).

  6. git switch master
git switch -c beta
    • Add an entry to HISTORY.md for the beta release
    • Update TIER.md to beta
    • Increment VERSION.md
    • Commit these three files
    git push -u origin beta
git switch master
git switch -c alpha

  7. Update /VERSION.md to the new version number, add and commit it.

  8. git push -u origin alpha

  9. On GitHub, protect the beta branch; subsequent changes will be accepted via PR.

  10. Unfreeze master branch

Note: search, e.g. \b14\.0\b and exclude: history.md,*.svg,*.dproj,package*.json,windows/src/ext/*,version.rc,manifest.xml. This gives a reasonable list of files where version number may have crept in.

  1. Create a PR for alpha, merge it. This starts a x.y.1 alpha build for master.
  2. Manually trigger the first beta build, making sure to set fromversion and toversion parameters (e.g. "[email protected]" and "[email protected]"). Note that this may not be needed in subsequent releases, because it may be linked to the switch from - to @ in release tags.

Website updates

  1. keyman.com/_includes/2020/KeymanVersion.php: update stable and beta version numbers

Moving to stable release

Note: this should never be done with PRs in beta that have not been merged.

  1. Freeze the beta branch
  2. Create embargo.txt with the contents being the version number of the release. See downloads README for details, and add it to the root of downloads.keyman.com to prevent the new version being publicised before it is all ready.
  3. Edit linux/debian/control and change the branch name in the Vcs-Git and Vcs-Browser fields to the new stable release (stable-16.0).
  4. git switch -c stable-16.0 beta
echo stable > TIER.md
git commit -m "chore: stable-16.0"
git push -u origin stable-16.0
  5. Protect the branch in GitHub (note: no action required, this happens automatically due to the branch protection rules)
  6. Create a new branch git switch -c chore/start-stable-17.0 stable-17.0
  7. Add stable-xx.0 trigger definitions to trigger-definitions.sh (e.g. see #6774), ready for commit
  8. Create a PR based on the stable branch, get it merged.
  9. Trigger the stable build for the stable-x.y branch in TeamCity (making sure you specify -f for the force parameter no longer required, due to above PR creating a history entry)
  10. Once all builds have finished successfully, and you are ready to publicise, remove embargo.txt from downloads.keyman.com again
  11. Make a final beta->master merge PR
  12. Delete beta branch

Windows Keyman API versions

The following locations are API versions and should be adjusted with caution:

  • Compiler.cpp VERSION_100 generation -> this is important to track because the versioning here is API level, not presentation.
  • kmcomapi.ridl - API version, stick with 10.0 I think? --> this is important to track because again the versioning here is API level.

Preparing Linux build for new major version

Jenkins must be updated to track the new stable- branch. The Groovy scripts for configuring it are at https://github.com/sillsdev/ci-builder-scripts with changes made via Gerrit. Follow CONTRIBUTING.md for setup. You will also need the following commit hook to push to Jenkins:

curl -Lo .git/hooks/commit-msg https://gerrit.lsdev.sil.org/tools/hooks/commit-msg

Note for the new stable-x branch, the regex in the /linux/*/debian/watch files will need to be modified to only watch stable. Otherwise, the scripts will detect the latest beta versions first.

Clone this wiki locally