From 44fa1e8e3af30d561de981a211ff7a79bfa36493 Mon Sep 17 00:00:00 2001 From: Wes Date: Mon, 3 Aug 2026 10:43:10 -0600 Subject: [PATCH] docs(release): align desktop handoff instructions (#3988) ## Summary - document exact-head trusted approval as the only desktop tagging authorization - explicitly require `desktop_ref=desktop-v` for the internal desktop handoff - replace the stale `squareup/sprout-releases` repository name with `squareup/buzz-releases` ## Audit coverage Compared `block/buzz` release documentation and automation with `squareup/buzz-releases` `main` (`5b09e5c5d71c80a0849a33458f4e45695df515d7`), including its README, agent guide, Buildkite field hint, desktop validator, release validation tests, and protected updater promotion instructions. ## Validation - `bash scripts/test-release-ref-contract.sh` - `git diff --check origin/main...HEAD` Signed-off-by: Wes Co-authored-by: Carl --- AGENTS.md | 4 ++-- RELEASING.md | 25 ++++++++++++++----------- 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4f03b312b..7cd43061b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,14 +13,14 @@ Buzz spans five repos. This one (`block/buzz`) is the OSS source for the relay, | Repo | Purpose | |------|---------| | [block/buzz](https://github.com/block/buzz) | OSS source — relay, desktop app, mobile app, CLI, agent harness | -| [squareup/sprout-releases](https://github.com/squareup/sprout-releases) | Buildkite pipeline producing Block-signed macOS + iOS builds with `-block` version suffix | +| [squareup/buzz-releases](https://github.com/squareup/buzz-releases) | Buildkite pipelines producing Block-signed macOS + iOS builds with `-block` desktop version suffix | | [squareup/sprout-oss](https://github.com/squareup/sprout-oss) | CI pipeline building the relay Docker image and pushing to internal ECR | | [squareup/block-coder-tf-stacks](https://github.com/squareup/block-coder-tf-stacks) | Terraform + ArgoCD deploying the relay to the staging Kubernetes cluster | | [squareup/sprout-backend-blox](https://github.com/squareup/sprout-backend-blox) | Desktop backend provider script connecting Blox workstation agents to the relay | ``` block/buzz (source) - ├─► sprout-releases (desktop + mobile builds → Artifactory, GitHub, Mobile Releases) + ├─► buzz-releases (desktop + mobile builds → Artifactory, GitHub, Mobile Releases) ├─► sprout-oss (relay Docker image → ECR) │ └─► block-coder-tf-stacks (Helm chart → ArgoCD → staging cluster) └─── sprout-backend-blox (Blox compute provider for Desktop agent launch) diff --git a/RELEASING.md b/RELEASING.md index e729f8b50..23dacea2c 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -56,14 +56,15 @@ or mobile GitHub Release. updates the PR. 2. Review the recorded base and candidate SHA, the complete changelog, and CI. The required **Desktop Release Candidate** check validates the exact head. - Authorization is either an approval on that exact head or a permitted Default - ruleset bypass at merge time. Any regeneration changes the head and requires - the checks—and, for the review path, approval—to run again. + A trusted repository member, owner, or collaborator must approve that exact + candidate head. Any regeneration or push changes the head, invalidates the + prior approval, and requires both the checks and approval to run again. 3. **Squash merge** the PR. The protected branch must still be exactly the recorded base; otherwise regenerate the candidate from current `main`. 4. `auto-tag-on-release-pr-merge` verifies the frozen parent, full-tree identity, - required checks, and one of the two authorization paths, then tags the squash - commit as `desktop-v`. + required checks, and trusted approval on the exact candidate head, then tags + the squash commit as `desktop-v`. An admin or ruleset bypass does not + authorize desktop tagging. 5. The tag triggers `release.yml`. It builds and stages Apple Silicon and Intel macOS, Windows, and Linux artifacts; publishes the versioned release only after the complete set succeeds; then updates the rolling updater manifest @@ -184,10 +185,12 @@ Buildkite pipeline accepts only an exact candidate tag. For mobile, trigger the private [Release Mobile pipeline](https://buildkite.com/runway/buzz-mobile-releases) with -an exact RC tag for the platform build being cut. For desktop, use -[Release Desktop](https://buildkite.com/runway/sprout-releases). See the +an exact RC tag for the platform build being cut. For desktop, start +[Release Desktop](https://buildkite.com/runway/sprout-releases) and enter the +exact public source tag as `desktop_ref=desktop-v`; a generic +`v` tag is intentionally rejected. See the [buzz-releases README](https://github.com/squareup/buzz-releases#cutting-a-release) -for the private pipeline contract. +for the rest of the private pipeline contract. --- @@ -269,9 +272,9 @@ actor list. Do not update the branch manually and do not weaken the ruleset. Run `just release-desktop ` again from current `main`; this regenerates the -candidate, reruns CI, and requires a fresh approval when using the review path. -The post-merge verifier refuses to tag a squash whose parent differs from the -recorded candidate base or whose tree differs from the validated PR head. +candidate, reruns CI, and requires a fresh trusted approval on the new exact +head. The post-merge verifier refuses to tag a squash whose parent differs from +the recorded candidate base or whose tree differs from the validated PR head. ### Local `just release-desktop` fails with "must be on main branch" Switch to `main` and pull latest before running the release recipe.