Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/android-r2-republish.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
name: Republish APK + AAB to R2 (interim manual)

# INTERIM / TEMPORARY tool (K2GO-457). It pushes the website APK (standard flavor) and the Play AAB
# (play flavor) to Cloudflare R2 BETWEEN tagged releases, while versionName stays on 1.1.0 and only
# versionCode moves. It OVERWRITES the live R2 objects the website serves (same filenames).
# (play flavor) to Cloudflare R2 BETWEEN tagged releases. Files are named after versionName, so a
# candidate build lands as K2Go-vX.Y.Z-rc.N-*. It OVERWRITES the live R2 objects the website serves (same filenames).
#
# What it does NOT do, on purpose:
# - No git tag, no GitHub Release (GitHub stays behind; R2 is the live copy).
Expand Down
5 changes: 5 additions & 0 deletions .github/workflows/android-release-build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ jobs:
ref: ${{ inputs.tag }}
submodules: recursive

# Fail before any build or upload when the tagged build is not that exact final version.
- name: Require versionName to equal the release tag
working-directory: ${{ github.workspace }}
run: python3 tools/play-publish/play_publish.py check-release --gradle controller/app/build.gradle --tag "$RELEASE_TAG"

# TODO (Future): Add a Jira step here to verify if the version exists in Jira
# or to extract release notes directly from a Jira board.

Expand Down
12 changes: 6 additions & 6 deletions .github/workflows/play-candidate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@ name: Play candidate (send a release candidate to Google review)

# K2GO-564, button 1 of the release flow. Design: controller/docs/ADR-K2GO-564-play-release-candidates.md
# Builds the Play AAB from the selected branch, takes the next versionCode from Play, sends the build
# to Google review on the chosen track and tags the commit vX.Y.Z-rc.N. Google gives its verdict by
# email and in Play Console (the API cannot read it). When Google approves, run "Play release" with
# the rc tag. If Google rejects, fix the code and run this workflow again: the next run is rc.N+1.
# to Google review on the chosen track and tags the commit with its versionName (vX.Y.Z-rc.N). Google
# gives its verdict by email and in Play Console (the API cannot read it). If Google rejects, fix the
# code, bump versionName to rc.N+1 and run this workflow again.
# Runs only from main. The internal track has no formal review, so an internal run gets no rc tag
# and cannot become a release.
#
# Preconditions: versionName in controller/app/build.gradle is the target version (vX.Y.Z, not yet
# released) and controller/ci/ota-release-notes.md has a "## vX.Y.Z" entry on top. Managed
# publishing is ON in Play Console, so an approved candidate waits instead of going live.
# Preconditions: versionName in controller/app/build.gradle is the next candidate (vX.Y.Z-rc.N, the
# tag this run creates) and controller/ci/ota-release-notes.md has a "## vX.Y.Z" entry on top.
# Managed publishing is ON in Play Console, so an approved candidate waits instead of going live.

on:
workflow_dispatch:
Expand Down
11 changes: 7 additions & 4 deletions .github/workflows/play-release.yml
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
name: Play release (publish an approved candidate)

# K2GO-564, button 2 of the release flow. Design: controller/docs/ADR-K2GO-564-play-release-candidates.md
# Run this after Google approved a candidate. It tags the SAME commit as the rc tag with the final
# version (v1.2.0-rc.2 -> v1.2.0) and runs the release build: GitHub Release, website APKs, R2 and
# the OTA update.json. Nothing is rebuilt for Play: in Play Console, press "Publish changes" to
# release the AAB that Google approved (Play has no API for that button).
# Run this after Google approved a candidate. It tags the candidate commit with the final version
# (v1.2.0-rc.2 -> v1.2.0) and runs the release build: GitHub Release, website APKs, R2 and the OTA
# update.json. An rc build is never released as final: the tagged commit must have versionName
# "v1.2.0" (check-release), so an rc commit is refused until the final-build step exists (K2GO-564).

on:
workflow_dispatch:
Expand Down Expand Up @@ -40,6 +40,9 @@ jobs:
git ls-remote --tags origin 'v*' | sed 's#.*refs/tags/##; s#\^{}$##' | sort -u > "$RUNNER_TEMP/tags.txt"
final=$(python3 tools/play-publish/play_publish.py final-tag --rc-tag "$RC_TAG" --tags "$RUNNER_TEMP/tags.txt")
git fetch --no-tags origin "refs/tags/$RC_TAG:refs/tags/$RC_TAG"
# An rc build is never released as final: the tagged commit must say versionName "$final".
git show "$RC_TAG:controller/app/build.gradle" > "$RUNNER_TEMP/build.gradle"
python3 tools/play-publish/play_publish.py check-release --gradle "$RUNNER_TEMP/build.gradle" --tag "$final"
git tag "$final" "$RC_TAG^{commit}"
git push origin "refs/tags/$final"
echo "tag=$final" >> "$GITHUB_OUTPUT"
Expand Down
8 changes: 3 additions & 5 deletions controller/app/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -44,15 +44,13 @@ android {

// 3. Version Control (OTA)
// NOTE: the APK carries this number x 10 (71 -> 710); see "VERSION CODE AND APK NAME" below
versionCode 72
versionCode 73
// Dynamic version suffix: CI passes -PversionSuffix explicitly; local builds fall back to
// the git short SHA (ADFA-4787) so any installed APK is traceable to its commit.
def ciSuffix = project.hasProperty('versionSuffix') ? project.property('versionSuffix')
: (project.ext.gitSha ? "-${project.ext.gitSha}" : "")

// Release candidate: v1.2.0-rc.1
versionName "v1.2.0${ciSuffix}" // rc.1

// A release candidate carries its rc label (v1.2.0-rc.1); only the final release drops it.
versionName "v1.2.0-rc.2${ciSuffix}"
buildConfigField "String", "GIT_SHA", "\"${project.ext.gitSha}\""
// Analytics is a per-flavor property (see productFlavors): the "standard" flavor turns it on
// when google-services.json is present; "fdroid" forces it off. The safe default here is OFF.
Expand Down
9 changes: 5 additions & 4 deletions controller/ci/ota-release-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,11 @@ Rule: the version header must match the release tag / `versionName` so the CI pi
the right entry.

## v1.2.0
Faster and more private. Official systems and your own backups install and
restore in about half the time. Each phone now has its own identity, copies leave
personal records behind, and a new Privacy screen keeps outside connections off
unless you turn them on.
Faster, simpler and more private. Official systems and your own backups install
and restore in about half the time. One app now fits every phone: a single download
replaces the separate 32-bit and 64-bit versions. Each phone has its own identity,
copies do not carry personal records, and a new Privacy screen keeps outside
connections off unless you turn them on.

## v1.1.0
A maintenance update. Code on the Go gains its add-ons gallery and offline build
Expand Down
31 changes: 18 additions & 13 deletions controller/docs/ADR-K2GO-564-play-release-candidates.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@
## Decision in one line

A release goes to Google review first, as a candidate (`vX.Y.Z-rc.N`). When Google approves
a candidate, we publish that exact build: Play releases the approved AAB, and GitHub tags the
same commit `vX.Y.Z`. We never rebuild after the approval.
a candidate, the final release is built from that code. Each build names itself: a candidate
says `vX.Y.Z-rc.N`, and only a build that says `vX.Y.Z` can become the release.

## Context (facts)

Expand All @@ -31,28 +31,33 @@ same commit `vX.Y.Z`. We never rebuild after the approval.

## Decision

1. Versions follow semver. `versionName` in `build.gradle` is the target version (`v1.2.0`) and
has no rc marker. The rc marker lives only in the git tag and in the Play release name.
1. Versions follow semver. `versionName` in `build.gradle` is the full label of the build:
`v1.2.0-rc.N` for a candidate, `v1.2.0` for the final release. The same label names the git
tag, the Play release and the R2 files, so a binary always says what it is.
A rejected candidate was never released, so the version stays the same and the next
candidate is `rc.N+1`. A change after `vX.Y.Z` is released is a new version (`vX.Y.Z+1`).
([semver items 3 and 9](https://semver.org/#spec-item-9))
2. Button 1, `play-candidate.yml`: build the Play AAB, take versionCode = highest code that
Play knows + 1, send to review with `ERROR_IF_IN_REVIEW`, tag the commit `vX.Y.Z-rc.N`, and
archive the AAB to R2. The rc tag is pushed only after Play accepts the upload. It runs only
from `main`. A run on the internal track (no formal review) gets no rc tag.
2. Button 1, `play-candidate.yml`: `versionName` must be the next candidate of an unreleased
version. Build the Play AAB, take versionCode = highest code that Play knows + 1, send to
review with `ERROR_IF_IN_REVIEW`, tag the commit with its `versionName`, and archive the AAB
to R2. The rc tag is pushed only after Play accepts the upload. It runs only from `main`.
A run on the internal track (no formal review) gets no rc tag.
3. Google approves or rejects (email, Play Console). A person reads the verdict.
4. Button 2, `play-release.yml`: accept only the newest rc of the version (each new candidate
replaces the older one in Play), tag its commit as `vX.Y.Z` and run the release build
(GitHub Release, website APKs, R2, OTA `update.json`). In Play Console, press
"Publish changes". The release build no longer builds a Play AAB, and it runs only when
`play-release.yml` calls it: a hand-pushed `v*` tag does not start a release.
replaces the older one in Play) and run the release build (GitHub Release, website APKs, R2,
OTA `update.json`). An rc build is never released as final: both the tag step and the
release build refuse a commit whose `versionName` is not exactly `vX.Y.Z`. The final build
(versionName `vX.Y.Z`, sent to Play, then tagged) is not designed yet, so today button 2
refuses every rc commit. The release build runs only when `play-release.yml` calls it:
a hand-pushed `v*` tag does not start a release.
5. Play credentials: a Google Cloud service account with "Release apps to testing tracks" on
this app only. Its JSON key is the secret `PLAY_SERVICE_ACCOUNT_JSON` of the GitHub
environment `google-play`, which asks a repo admin to approve each run.

## Consequences

- What users get from Play is the binary Google approved. GitHub and Play show the same version.
- Every binary shows its real label (Settings > About, file names), so an rc build is never
mistaken for the release. The final build is a new versionCode, so Google reviews it again.
- A rejection costs a new candidate, not a new version number.
- The Play versionCode comes from Play, so it can differ from `versionCode * 10` in
`build.gradle`. The website APKs keep the `build.gradle` codes. The two channels have
Expand Down
45 changes: 38 additions & 7 deletions tools/play-publish/play_publish.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
plan --gradle F --notes F --tags F print version, rc tag and release notes as GitHub outputs
next-code --package P --base N print the Play versionCode for the next upload
final-tag --rc-tag T --tags F print the release tag for an approved candidate
check-release --gradle F --tag T fail unless versionName is exactly the final tag T
publish --package P --track T --aab F --code N --name S --notes-file F
"""
import argparse
Expand All @@ -30,7 +31,8 @@
UPLOAD_API = "https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications"
SCOPE = "https://www.googleapis.com/auth/androidpublisher"
NOTES_MAX = 500 # Play limit for "What's new" per language.
SEMVER = re.compile(r"^v(\d+)\.(\d+)\.(\d+)$")
SEMVER = re.compile(r"^v\d+\.\d+\.\d+$")
LABEL = re.compile(r"^(v\d+\.\d+\.\d+)(?:-rc\.(\d+))?$")
RC_TAG = re.compile(r"^(v\d+\.\d+\.\d+)-rc\.(\d+)$")


Expand All @@ -41,16 +43,37 @@ class PlanError(Exception):
# ---- pure rules (unit-tested) -------------------------------------------------------------

def version_name(gradle_text):
"""The release version in build.gradle, e.g. "v1.2.0". Must be plain semver: the rc
marker lives in the git tag and the Play release name, never in the binary."""
"""The version label in build.gradle: "v1.2.0-rc.1" for a candidate, "v1.2.0" for the
final release. The same label names the git tag, the Play release and the R2 files."""
m = re.search(r'versionName\s+"(v[^"$]+)\$\{ciSuffix\}"', gradle_text)
if not m:
raise PlanError("versionName not found in build.gradle")
if not SEMVER.match(m.group(1)):
raise PlanError("versionName %r is not vMAJOR.MINOR.PATCH" % m.group(1))
if not LABEL.match(m.group(1)):
raise PlanError("versionName %r is not vMAJOR.MINOR.PATCH[-rc.N]" % m.group(1))
return m.group(1)


def candidate_tag(tags, label):
"""The rc tag of a candidate build is its versionName. It must be the next candidate of an
unreleased version, so a used, skipped or final label is refused."""
m = LABEL.match(label)
if not m or m.group(2) is None:
raise PlanError("versionName %r is not a candidate (vX.Y.Z-rc.N)" % label)
expected = next_rc_tag(tags, m.group(1))
if label != expected:
raise PlanError("versionName is %s; the next candidate is %s" % (label, expected))
return label


def check_release(gradle_text, tag):
"""A release tag goes only on a build whose versionName is that exact final version:
an rc build is never released as final."""
label = version_name(gradle_text)
if label != tag or not SEMVER.match(tag):
raise PlanError("versionName is %s, so this build cannot be released as %s" % (label, tag))
return tag


def version_code_base(gradle_text):
m = re.search(r"^\s*versionCode\s+(\d+)\s*$", gradle_text, re.M)
if not m:
Expand Down Expand Up @@ -191,9 +214,9 @@ def open_edit(self):

def cmd_plan(args):
gradle = open(args.gradle, encoding="utf-8").read()
version = version_name(gradle)
tags = set(open(args.tags, encoding="utf-8").read().split())
rc = next_rc_tag(tags, version)
rc = candidate_tag(tags, version_name(gradle))
version = RC_TAG.match(rc).group(1)
notes = release_notes(open(args.notes, encoding="utf-8").read(), version)
with open(args.notes_out, "w", encoding="utf-8") as f:
f.write(notes)
Expand Down Expand Up @@ -222,6 +245,10 @@ def cmd_final_tag(args):
print(final_tag(tags, args.rc_tag))


def cmd_check_release(args):
print(check_release(open(args.gradle, encoding="utf-8").read(), args.tag))


def cmd_publish(args):
play = Play(args.package)
notes = open(args.notes_file, encoding="utf-8").read()
Expand Down Expand Up @@ -257,6 +284,10 @@ def main(argv=None):
s.add_argument("--rc-tag", required=True)
s.add_argument("--tags", required=True, help="file with one git tag name per line")
s.set_defaults(func=cmd_final_tag)
s = sub.add_parser("check-release")
s.add_argument("--gradle", required=True)
s.add_argument("--tag", required=True)
s.set_defaults(func=cmd_check_release)
s = sub.add_parser("publish")
s.add_argument("--package", required=True)
s.add_argument("--track", required=True, choices=["internal", "alpha", "beta", "production"])
Expand Down
45 changes: 39 additions & 6 deletions tools/play-publish/test_play_publish.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,25 +7,58 @@
defaultConfig {
versionCode 71
def ciSuffix = ""
versionName "v1.2.0${ciSuffix}"
versionName "v1.2.0-rc.1${ciSuffix}"
}
'''
FINAL = GRADLE.replace("v1.2.0-rc.1", "v1.2.0")


class VersionTest(unittest.TestCase):
def test_reads_version_and_code_base(self):
self.assertEqual("v1.2.0", pp.version_name(GRADLE))
def test_reads_label_and_code_base(self):
self.assertEqual("v1.2.0-rc.1", pp.version_name(GRADLE))
self.assertEqual("v1.2.0", pp.version_name(FINAL))
self.assertEqual(71, pp.version_code_base(GRADLE))

def test_rejects_a_prerelease_in_the_binary(self):
with self.assertRaises(pp.PlanError):
pp.version_name(GRADLE.replace("v1.2.0", "v1.2.0-rc.1"))
def test_rejects_other_labels(self):
for bad in ("v1.2.0-beta", "v1.2.0-rc1", "1.2.0", "v1.2.0-rc.1-x"):
with self.assertRaises(pp.PlanError):
pp.version_name(GRADLE.replace("v1.2.0-rc.1", bad))

def test_reports_a_missing_version(self):
with self.assertRaises(pp.PlanError):
pp.version_name("versionCode 71")


class CandidateTagTest(unittest.TestCase):
def test_label_is_the_next_candidate(self):
self.assertEqual("v1.2.0-rc.1", pp.candidate_tag({"v1.1.0"}, "v1.2.0-rc.1"))
self.assertEqual("v1.2.0-rc.2", pp.candidate_tag({"v1.2.0-rc.1"}, "v1.2.0-rc.2"))

def test_used_skipped_and_final_labels_are_refused(self):
tags = {"v1.1.0", "v1.2.0-rc.1"}
for bad in ("v1.2.0-rc.1", "v1.2.0-rc.3", "v1.2.0"):
with self.assertRaises(pp.PlanError):
pp.candidate_tag(tags, bad)

def test_a_released_version_is_closed(self):
with self.assertRaises(pp.PlanError):
pp.candidate_tag({"v1.2.0", "v1.2.0-rc.1"}, "v1.2.0-rc.2")


class CheckReleaseTest(unittest.TestCase):
def test_final_build_matches_its_tag(self):
self.assertEqual("v1.2.0", pp.check_release(FINAL, "v1.2.0"))

def test_an_rc_build_is_never_released_as_final(self):
with self.assertRaises(pp.PlanError):
pp.check_release(GRADLE, "v1.2.0")

def test_tag_and_label_must_be_the_same_final_version(self):
for tag in ("v1.2.1", "v1.2.0-rc.1"):
with self.assertRaises(pp.PlanError):
pp.check_release(FINAL if tag == "v1.2.1" else GRADLE, tag)


class RcTagTest(unittest.TestCase):
def test_first_candidate_is_rc1(self):
self.assertEqual("v1.2.0-rc.1", pp.next_rc_tag({"v1.1.0", "v1.0.0"}, "v1.2.0"))
Expand Down
Loading