Skip to content

Release workflow

Jump to bottom
Darcy Wong edited this page Oct 8, 2019 · 51 revisions

Alpha/nightly

While we are doing active development on a product, we will have per-commit alpha master builds and nightly builds. The nightly build simply takes the last successful alpha master build and publishes it to downloads.keyman.com as "alpha".

User Test

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

Copy the checklist into an issue before starting the transition. When creating PRs that target beta, add the checklist as a comment to the PR. Each item should ideally be checked off by the tester before beta is started or the PR is merged.

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.

Notes for Android

Note: The build counters are handled slightly differently given a product version mm.nn.bbbb (major.minor.build counter). The unique Nightly/Beta/Stable build number are used for the versionCodes in the Google Play store to distinguish builds. Make sure you adjust the CI Build number and Build counters appropriately (in this order):

  1. Beta
    • build counter: manually set to next value of the current nightly build counter
  2. Master
    • build counter: Reset to 1
  3. Nightly
    • build counter: Increment to the nearest 2000. This reserves enough beta/stable builds.
    • 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.

Don't Forget: The encumbered components also need to go through the same branching to beta/stable-x.x.

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. In TeamCity:

    1. Update build_counter on the beta build to be one higher than the current master build.
    2. Update the TeamCity variables keyman.major.version.beta and keyman.major.version.alpha.
    3. On the master build, reset build_counter.

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

  7. git checkout -b beta master
git push -u origin beta
git checkout -b alpha master

  8. Add a note to */history.MD to reflect the incremented version and commit it to alpha. See https://github.com/keymanapp/keyman/wiki/history.MD-format for format.

  9. git push -u origin alpha

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

  11. Unfreeze master branch

  12. Update the following files with the new version:

    • resources/VERSION.md
    • windows/src/Defines.mak
    • windows/src/global/delphi/general/KeymanVersion.pas
    • windows/src/global/inc/keymanversion.h
    • mac/Keyman4Mac/Keyman4Mac.xcodeproj/project.pbxproj
    • mac/Keyman4MacIM/Keyman4MacIM.xcodeproj/project.pbxproj
    • mac/KeymanEngine4Mac/KeymanEngine4Mac.xcodeproj/project.pbxproj

    Note: search, e.g. \b12\.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.

  13. Create a PR for alpha, merge it. This starts a n.1 alpha build for master.

Notes for Linux

Make sure the environment variable TIER is correctly set on the build agent. (Refer to PR #1670 )

Website updates

  1. keyman.com/_includes/includes.servervars.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. In TeamCity, update build_counter on the stable build to be higher than the current beta build, for all projects. We are moving up to the next round number, e.g. instead of 167 we go to 200. This is for mnemonic purposes only.
  3. Update the teamcity variable keyman.major.version.stable 
  4. git checkout -b stable-10.0 beta
git push origin stable-10.0
  5. Protect the branch in GitHub

Preparing Windows build for new major version

When starting a new major version, the following files need to be updated:

  • windows/src/version.txt (Master version number)
  • windows/src/global/delphi/general/KeymanVersion.pas (Add new version and update macro references)
  • windows/src/global/inc/keymanversion.h (Add new version and update macro references)
  • windows/src/README.md (Any documentation about new version)

The default build number is also stored in windows/src/version.txt, so when doing local test builds you may want to adjust it accordingly. The CI infrastructure automatically updates version.txt for true release builds.

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.

Clone this wiki locally