From 81f0de6eda7fd801926c22c111ad36009aeb1206 Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Mon, 9 Nov 2026 19:34:17 +0700 Subject: [PATCH] ci(release): tag with one script, forward-port at merge and hold CI while a tag starts --- .claude/skills/release/SKILL.md | 5 +- apple/RELEASING.md | 20 ++-- apple/scripts/release/tag.sh | 52 ++++++++++ apple/scripts/release/test_tag.py | 156 ++++++++++++++++++++++++++++++ 4 files changed, 220 insertions(+), 13 deletions(-) create mode 100755 apple/scripts/release/tag.sh create mode 100644 apple/scripts/release/test_tag.py diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index 23218c07bd..223fd44a81 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -58,8 +58,9 @@ For a stable or patch, name the fix and the reason, and ask. Only a security fix ## 6. Follow RELEASING -Run `apple/RELEASING.md`: Cutting a beta, or Cutting a stable or patch, then Forward-port. On a failure, When a run fails or Withdrawing a release. +Run `apple/RELEASING.md`: Cutting a beta, or Cutting a stable or patch with its Forward-port. On a failure, When a run fails or Withdrawing a release. -- Watch the tag's run: `gh run list --workflow release.yml --limit 3`, then `gh run watch --exit-status`. +- `apple/scripts/release/tag.sh ` tags and watches the tag's run. Hold merges and pull request pushes around it as Tagging says, since release jobs get no runner priority. +- The forward-port goes once the tag's App and Plugins jobs start, not after publishing, so the next beta.1 need not wait for the stable (Forward-port). - Then check the source: `gh api -H 'Accept: application/vnd.github.raw' 'repos/TableProApp/TablePro/contents/appcast.xml?ref=gh-pages' | grep -c 'X.Y.Z<'` prints 1; `gh release view vX.Y.Z --json assets -q '.assets | length'` is 4 plus `python3 apple/scripts/release/registry.py targets | wc -l`. - After an X.Y.0, the `announce` skill in TableProApp/web is next. diff --git a/apple/RELEASING.md b/apple/RELEASING.md index 9275ea5a00..35cdb617e1 100644 --- a/apple/RELEASING.md +++ b/apple/RELEASING.md @@ -48,21 +48,18 @@ gh pr merge --auto --squash ## Tagging -A tag goes on a line commit once that commit's CI push run is green. Tags never move, so check the tag before it leaves the machine: `version.py check` runs the same gate as `verify`. +A tag goes on a line commit once that commit's CI push run is green. Tags never move, so the tag is checked before it leaves the machine: `version.py check` runs the same gate as `verify`. ```bash -git fetch origin --tags -gh run list --workflow ci.yml --branch release/X.Y --event push --commit -gh run watch --exit-status -git tag -s -m -python3 apple/scripts/release/version.py check && git push origin +apple/scripts/release/tag.sh ``` -On an error, `git tag -d `, fix the cause and tag again. +- It waits for the line's CI push run on the commit, signs the tag, runs `version.py check`, pushes the tag and watches its Release run. A failed check deletes the local tag: fix the cause and run it again. +- Release jobs get no priority on hosted runners: they queue behind every macOS job already waiting. Run it when no other CI run is in flight (`gh run list --workflow ci.yml --status in_progress`, then `--status queued`). Merge nothing and push to no pull request until the tag's App and Plugins jobs have started. ## Cutting a beta -1. beta.1 only: `main` has the last stable's forward-port. Cut the line at the newest `main` commit with a green CI push run, after the storage check up to it: +1. beta.1 only: `main` has the last stable's forward-port, which needs its release PR merged, not published (Forward-port). Cut the line at the newest `main` commit with a green CI push run, after the storage check up to it: ```bash git fetch origin @@ -98,6 +95,7 @@ A beta gets no `CHANGELOG.md` section: its notes are a towncrier draft of the fr ``` 5. Tag its merge commit, `gh pr view --json mergeCommit -q .mergeCommit.oid`, as `vX.Y.Z` (Tagging). +6. Forward-port it (Forward-port). ### Notes @@ -106,7 +104,7 @@ A beta gets no `CHANGELOG.md` section: its notes are a towncrier draft of the fr ## Forward-port -Once a stable or patch publishes, cherry-pick its release commit to `main`, and to a newer open line when one exists. The next tag refuses to build without its heading. +Once the release PR of a stable or patch merges and its tag's App and Plugins jobs have started, cherry-pick its release commit to `main`, and to a newer open line when one exists. It does not wait for the release to publish. The next tag refuses to build without its heading. ```bash git fetch origin && git switch -c forward/vX.Y.Z origin/main @@ -117,7 +115,7 @@ gh pr merge --auto - A newer open line gets the same PR from `origin/release/`, with `--base release/`. - A conflict on a fragment: `git rm` it. On `CHANGELOG.md`: keep both sections, in version order. -- Then `python3 apple/scripts/release/notes.py docs X.Y.Z --ref vX.Y.Z --mdx ../tablepro-docs/changelog.mdx` goes into a `docs(changelog): vX.Y.Z` PR in TableProApp/docs, merged by hand once green. +- Once the release publishes, `python3 apple/scripts/release/notes.py docs X.Y.Z --ref vX.Y.Z --mdx ../tablepro-docs/changelog.mdx` goes into a `docs(changelog): vX.Y.Z` PR in TableProApp/docs, merged by hand once green. ## When a run fails @@ -126,7 +124,7 @@ Nothing reaches users before the `github-release` job of `release.yml`. - Tags never move, with no bypass. A burned number stays burned; the fix ships as the next number. - `verify` names the broken rule, or the CI run that is still going, red or missing. Once that run is green: `gh run rerun --failed`. - An infrastructure failure (runner, network, notary service) is the same re-run, before or after publishing: each step skips what is done. A code failure is fixed on `main`, picked, and ships as the next number. -- A stable that never published: the next release PR runs `git revert ` before `assemble`, and `gh release delete vX.Y.Z --yes` removes a leftover draft. +- A stable that never published: the next release PR runs `git revert ` before `assemble`, and its forward-port takes the revert to `main` and the newer line with the new section. `gh release delete vX.Y.Z --yes` removes a leftover draft. - A stable builds only on a GA Xcode (`setup-xcode` `require-release`). With none on the runner image, `app` and `plugins` fail, and a PR points `.github/actions/setup-xcode` at an image that has one. Betas still ship. - `feed` fails with "no signature vouches for the published plugins/v3.json" on the first release that signs the manifest, or after a release line without signing published it. Check `plugins/v3.json` on `gh-pages`, run `gh variable set PLUGIN_MANIFEST_RESIGN --body true`, then `gh run rerun --failed`, then `gh variable delete PLUGIN_MANIFEST_RESIGN`. diff --git a/apple/scripts/release/tag.sh b/apple/scripts/release/tag.sh new file mode 100755 index 0000000000..c77a0896a3 --- /dev/null +++ b/apple/scripts/release/tag.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Usage: tag.sh +# apple/RELEASING.md, Tagging: waits for the line's CI push run on , signs on it, checks it with +# version.py, pushes it and watches the tag's Release run. A failed check deletes the local tag. + +die() { + echo "tag.sh: $*" >&2 + exit 1 +} + +if [ $# -ne 2 ]; then + echo "Usage: tag.sh " >&2 + exit 2 +fi +TAG="$1" +COMMIT="$2" + +cd "$(git rev-parse --show-toplevel)" +LINE="$(python3 apple/scripts/release/version.py parse "$TAG" | sed -n 's/^line=//p')" +git fetch origin --tags +SHA="$(git rev-parse --verify "$COMMIT^{commit}")" + +# A push starts its runs a few seconds later. +run_id() { + local id + for _ in 1 2 3 4 5 6; do + id="$(gh run list "$@" --limit 1 --json databaseId --jq '.[0].databaseId // empty')" + if [ -n "$id" ]; then + echo "$id" + return 0 + fi + sleep 10 + done + return 1 +} + +CI_RUN="$(run_id --workflow ci.yml --branch "release/$LINE" --event push --commit "$SHA")" \ + || die "no CI push run on release/$LINE at $SHA" +gh run watch "$CI_RUN" --exit-status --interval 30 || die "the CI push run on $SHA did not pass" + +git tag -s "$TAG" -m "$TAG" "$SHA" +if ! python3 apple/scripts/release/version.py check "$TAG"; then + git tag -d "$TAG" + die "$TAG cannot build; fix the cause and run tag.sh again" +fi +git push origin "$TAG" + +RELEASE_RUN="$(run_id --workflow release.yml --branch "$TAG" --event push)" \ + || die "$TAG is pushed, but its Release run has not started: gh run list --workflow release.yml --limit 3" +gh run watch "$RELEASE_RUN" --exit-status --interval 60 diff --git a/apple/scripts/release/test_tag.py b/apple/scripts/release/test_tag.py new file mode 100644 index 0000000000..d318e17a34 --- /dev/null +++ b/apple/scripts/release/test_tag.py @@ -0,0 +1,156 @@ +#!/usr/bin/env python3 + +import os +import subprocess +import tempfile +import unittest +from pathlib import Path + +SCRIPT = Path(__file__).resolve().parent / "tag.sh" + +STUBS = { + "gh": r"""#!/usr/bin/env bash +set -euo pipefail +echo "gh $*" >> "$STUB_STATE/calls" +case "$1 $2" in + "run list") + case "$*" in + *--workflow\ ci.yml*) echo "${CI_RUN:-}" ;; + *--workflow\ release.yml*) echo "${RELEASE_RUN:-}" ;; + esac + ;; + "run watch") [ "$3" != "${RED_RUN:-}" ] ;; + *) echo "stub gh: unexpected $*" >&2; exit 99 ;; +esac +""", + "sleep": """#!/usr/bin/env bash +echo "sleep $1" >> "$STUB_STATE/calls" +""", + # git signs a tag with " --status-fd=2 -bsau " and wants SIG_CREATED on that descriptor. + "gpg": r"""#!/usr/bin/env bash +cat > /dev/null +printf '\n[GNUPG:] SIG_CREATED D 1 8 00 0 0\n' >&2 +printf -- '-----BEGIN PGP SIGNATURE-----\n\nstub\n-----END PGP SIGNATURE-----\n' +""", +} + +VERSION_STUB = """import os +import sys + +if sys.argv[1] == "parse": + print("version=0.82.1\\nbuild=820199\\nchannel=stable\\nline=0.82") +else: + with open(os.path.join(os.environ["STUB_STATE"], "calls"), "a") as calls: + calls.write(f"check {sys.argv[2]}\\n") + sys.exit(int(os.environ.get("CHECK_EXIT", "0"))) +""" + + +class TagTests(unittest.TestCase): + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + root = Path(directory.name) + self.bin = root / "bin" + self.state = root / "state" + self.repo = root / "repo" + self.origin = root / "origin.git" + for path in (self.bin, self.state, self.repo): + path.mkdir() + for name, body in STUBS.items(): + stub = self.bin / name + stub.write_text(body, encoding="utf-8") + stub.chmod(0o755) + self.env = { + **{key: value for key, value in os.environ.items() if not key.startswith("GIT_")}, + "PATH": f"{self.bin}{os.pathsep}{os.environ['PATH']}", + "STUB_STATE": str(self.state), + "GIT_CONFIG_GLOBAL": os.devnull, + "GIT_CONFIG_NOSYSTEM": "1", + "GIT_CONFIG_COUNT": "1", + "GIT_CONFIG_KEY_0": "gpg.program", + "GIT_CONFIG_VALUE_0": str(self.bin / "gpg"), + "GIT_AUTHOR_NAME": "Fixture", + "GIT_AUTHOR_EMAIL": "fixture@example.com", + "GIT_COMMITTER_NAME": "Fixture", + "GIT_COMMITTER_EMAIL": "fixture@example.com", + "CI_RUN": "11", + "RELEASE_RUN": "22", + } + self.git("init", "--quiet", "--bare", str(self.origin), cwd=root) + self.git("init", "--quiet", "--initial-branch=release/0.82") + version = self.repo / "apple/scripts/release/version.py" + version.parent.mkdir(parents=True) + version.write_text(VERSION_STUB, encoding="utf-8") + self.git("add", "--all") + self.git("commit", "--quiet", "-m", "chore(release): v0.82.1") + self.git("remote", "add", "origin", str(self.origin)) + self.git("push", "--quiet", "origin", "HEAD") + self.sha = self.git("rev-parse", "HEAD") + + def git(self, *args, cwd=None): + return subprocess.run(["git", *args], cwd=cwd or self.repo, env=self.env, check=True, + capture_output=True, text=True).stdout.strip() + + def tag(self, **env): + return subprocess.run(["bash", str(SCRIPT), "v0.82.1", "HEAD"], cwd=self.repo, env={**self.env, **env}, + capture_output=True, text=True) + + def calls(self): + calls = self.state / "calls" + return calls.read_text(encoding="utf-8").splitlines() if calls.exists() else [] + + def local_tags(self): + return self.git("tag", "--list") + + def pushed_tags(self): + return self.git("--git-dir", str(self.origin), "tag", "--list") + + def test_a_green_run_and_check_push_a_signed_tag_and_watch_its_release(self): + result = self.tag() + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(self.calls(), [ + f"gh run list --workflow ci.yml --branch release/0.82 --event push --commit {self.sha} --limit 1 " + "--json databaseId --jq .[0].databaseId // empty", + "gh run watch 11 --exit-status --interval 30", + "check v0.82.1", + "gh run list --workflow release.yml --branch v0.82.1 --event push --limit 1 " + "--json databaseId --jq .[0].databaseId // empty", + "gh run watch 22 --exit-status --interval 60", + ]) + self.assertEqual(self.pushed_tags(), "v0.82.1") + self.assertEqual(self.git("rev-parse", "v0.82.1^{commit}"), self.sha) + self.assertIn("-----BEGIN PGP SIGNATURE-----", self.git("cat-file", "tag", "v0.82.1")) + + def test_a_red_ci_run_tags_nothing(self): + result = self.tag(RED_RUN="11") + self.assertEqual(result.returncode, 1) + self.assertIn(f"the CI push run on {self.sha} did not pass", result.stderr) + self.assertNotIn("check v0.82.1", self.calls()) + self.assertEqual(self.local_tags(), "") + self.assertEqual(self.pushed_tags(), "") + + def test_a_failed_check_deletes_the_tag_and_pushes_nothing(self): + result = self.tag(CHECK_EXIT="1") + self.assertEqual(result.returncode, 1) + self.assertIn("v0.82.1 cannot build", result.stderr) + self.assertEqual(self.calls()[-1], "check v0.82.1") + self.assertEqual(self.local_tags(), "") + self.assertEqual(self.pushed_tags(), "") + + def test_a_missing_ci_run_is_waited_for_then_refused(self): + result = self.tag(CI_RUN="") + self.assertEqual(result.returncode, 1) + self.assertIn(f"no CI push run on release/0.82 at {self.sha}", result.stderr) + self.assertEqual(self.calls().count("sleep 10"), 6) + self.assertEqual(self.local_tags(), "") + + def test_a_missing_argument_prints_the_usage(self): + result = subprocess.run(["bash", str(SCRIPT), "v0.82.1"], cwd=self.repo, env=self.env, + capture_output=True, text=True) + self.assertEqual(result.returncode, 2) + self.assertEqual(self.calls(), []) + + +if __name__ == "__main__": + unittest.main()