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
5 changes: 3 additions & 2 deletions .claude/skills/release/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <id> --exit-status`.
- `apple/scripts/release/tag.sh <tag> <commit>` 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 '<sparkle:shortVersionString>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.
20 changes: 9 additions & 11 deletions apple/RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <commit>
gh run watch <run id> --exit-status
git tag -s <tag> -m <tag> <commit>
python3 apple/scripts/release/version.py check <tag> && git push origin <tag>
apple/scripts/release/tag.sh <tag> <commit>
```

On an error, `git tag -d <tag>`, 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
Expand Down Expand Up @@ -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 <PR> --json mergeCommit -q .mergeCommit.oid`, as `vX.Y.Z` (Tagging).
6. Forward-port it (Forward-port).

### Notes

Expand All @@ -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
Expand All @@ -117,7 +115,7 @@ gh pr merge --auto

- A newer open line gets the same PR from `origin/release/<line>`, with `--base release/<line>`.
- 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

Expand All @@ -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 <release run> --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 <its release commit>` 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 <its release commit>` 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 <release run> --failed`, then `gh variable delete PLUGIN_MANIFEST_RESIGN`.

Expand Down
52 changes: 52 additions & 0 deletions apple/scripts/release/tag.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
#!/usr/bin/env bash
set -euo pipefail

# Usage: tag.sh <tag> <commit>
# apple/RELEASING.md, Tagging: waits for the line's CI push run on <commit>, signs <tag> 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 <tag> <commit>" >&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
156 changes: 156 additions & 0 deletions apple/scripts/release/test_tag.py
Original file line number Diff line number Diff line change
@@ -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 "<gpg.program> --status-fd=2 -bsau <key>" 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()
Loading