diff --git a/.claude/commands/write_release_descriptions.md b/.claude/commands/write_release_descriptions.md index cd240cfb009..951dc0f003a 100644 --- a/.claude/commands/write_release_descriptions.md +++ b/.claude/commands/write_release_descriptions.md @@ -6,19 +6,17 @@ description: Write CLI release description and generate RELEASE_NOTES given a ch You need to create release documentation for Shopify CLI based on the changeset PR at: $ARGUMENTS -For `main`, the version bump is made upstream, in Shopify's internal monorepo, with `pnpm changeset-manifests`, and the mirror carries it here: it opens or refreshes a pull request automatically after each upstream merge and merges it once `main`'s required checks pass. Never merge "Version Packages - main" here: the mirror would refuse every later publish. `stable/*` patch lines keep their own "Version Packages - stable/X.Y" pull requests here. +The input is a "Version Packages - stable/X.Y" pull request, for a minor (`X.Y.0`) or a patch release: minors and patches both ship from `stable/X.Y`. `main` never publishes a release, so there is no "Version Packages - main" pull request to read. ## Step 1: Generate Release Markdown First, review the changeset PR to understand what's being released. Look for: - The version number (e.g., 3.86.0) - All changes listed in the PR body -- Commit hashes that need to be converted to PR links -For each change with a commit hash: -1. Use `git log --oneline --grep="HASH" -n 20` to find the commit -2. Use `git log --oneline --merges -n 50` to find the merge commit with PR number -3. Extract the PR number from the merge commit message +Lines cut after the move (5.1 and later) have no commit hashes in their changelog entries. On `stable/5.0` and older, each entry starts with a short hash: `gh api repos/Shopify/cli/commits/HASH/pulls --jq '.[] | select(.base.ref == "stable/X.Y") | .number'` gives its backport pull request. For entries without a hash: +- For a minor, find the commit that added each changeset (`gh api "repos/Shopify/cli/commits?sha=stable/X.Y&path=.changeset/NAME.md" --jq '.[].sha'`) and its pull request (`gh api repos/Shopify/cli/commits/HASH/pulls`). Link a pull request that merged on this repository before the CLI moved upstream. A pull request that the mirror's bot account opened carries an upstream change: list that change without a link, and tell the user which changes have no link. +- For a patch, each change merged through a backport pull request into `stable/X.Y`. List the changeset files the PR deletes with `gh pr view -R Shopify/cli --json files --jq '.files[].path | select(startswith(".changeset/"))'`. For each one, `git log origin/stable/X.Y --diff-filter=A --format=%H -- ` prints the commit that added it, and `gh api repos/Shopify/cli/commits/HASH/pulls --jq '.[] | select(.base.ref == "stable/X.Y") | .number'` prints the backport pull request. Link that pull request. Create a release markdown with this format: @@ -41,11 +39,11 @@ IMPORTANT: Do not modify the description language from the changeset PR. We are Please present the content to the user for approval. Before doing so, double-check that you've not modified wording from the changeset PR, only link formatting and ordering. -Once the format and wording have been approved, please copy the text to the system clipboard so that it can be pasted into the GitHub release form. +Once the format and wording have been approved, please copy the text to the system clipboard. The release workflow creates the GitHub release from the changelog entries (except for `X.0.0`), so paste it there by editing that release once it exists. ## Step 2: Create Partner Release Notes -Based on the release markdown from Step 1, create a file at `RELEASE_NOTES/{VERSION}.md` (extract version from the PR). For a `main` release, create it upstream, in Shopify's internal monorepo, which the mirror publishes here; don't commit it to this repository's `main`. +Based on the release markdown from Step 1, create a file at `RELEASE_NOTES/{VERSION}.md` (extract version from the PR). For a minor release, create it upstream, in Shopify's internal monorepo, which the mirror publishes here; don't commit it to this repository's `main` or `stable/X.Y`. The main change you're making here is to remove the PR links from step one. The rest of the content can remain. @@ -68,10 +66,6 @@ After creating the file: 1. Stage it with `git add RELEASE_NOTES/{VERSION}.md` 2. Commit with message: `Release notes for {VERSION}` -## Step 4: Check the Stable Branch (X.Y.0 releases only) - -After the release job for an `X.Y.0` release finishes, check that `stable/X.Y` exists with `git ls-remote --heads origin stable/X.Y`. If it doesn't, the job summary says so: ask a Dev Experience member to create it from the release tag with `git push origin refs/tags/X.Y.0:refs/heads/stable/X.Y`. Only Dev Experience members can create stable branches, and changes to `stable/*` need a pull request with code-owner review. - ## Example Output For a 3.86.0 release, you would create `RELEASE_NOTES/3.86.md`: diff --git a/AGENTS.md b/AGENTS.md index 96c47838e55..51646060546 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,11 +57,13 @@ If the change is not ready to be public, do not add a changeset. ## Releases -- `main`'s version bump is made upstream, in Shopify's internal monorepo, with `pnpm changeset-manifests`. The mirror carries it here: it opens or refreshes a pull request automatically after each upstream merge and merges it once `main`'s required checks pass, and `release.yml` publishes as before. +- Minor and patch releases ship from `stable/X.Y` branches. `main` never publishes a release: its version bump is made upstream, in Shopify's internal monorepo, after npm has the release, and the mirror carries it here. Nightlies still publish from `main`. - Never merge "Version Packages - main" here. It would put commits on `main` that the mirror didn't make, and the mirror would refuse every later publish. -- `stable/*` patch lines keep their own "Version Packages - stable/X.Y" pull requests here. GitHub Actions can't open them, so a Dev Experience member opens each one from `changeset-release/stable/X.Y`. -- Each `X.Y.0` release gets a `stable/X.Y` branch for its patch releases. Only Dev Experience members can create one: after the release job, a Dev Experience member creates it from the release tag with `git push origin refs/tags/X.Y.0:refs/heads/stable/X.Y`. -- Changes to `stable/*` branches, such as patch-release backports and their "Version Packages" pull requests, go through a pull request that a Dev Experience member merges with the branch rules' bypass (`gh pr merge --merge --admin`), with no review. Do not push to them directly. +- Before a minor release, a Dev Experience member creates `stable/X.Y` at a green `main` commit with `git push origin :refs/heads/stable/X.Y`. Only Dev Experience members can create `stable/*` branches or push to them without a pull request. Force-pushes and deletions stay blocked. +- Every release, minor or patch, is a "Version Packages - stable/X.Y" pull request. `release.yml`'s Version Packages job pushes the version bump to `changeset-release/stable/X.Y`, but GitHub Actions can't open pull requests here, so a Dev Experience member opens it by hand, closes and reopens it so its checks run, and tests its head commit `H` with the Release QA package workflow (`release-qa-package.yml`). +- The release owner merges it once `stable/X.Y`'s head is `H`'s parent, with `gh pr merge -R Shopify/cli --merge --admin --match-head-commit `. Use a merge commit (`--merge`): a squash merge publishes nothing. That merge publishes the versions it changed, and nothing else. +- While a release is open, only its release owner merges into `stable/X.Y`. Anyone else, people and agents alike, asks the release owner first. +- A patch starts with a backport pull request into `stable/X.Y` with the fix and the same changeset file as on `main`. A Dev Experience member merges it with the branch rules' bypass (`gh pr merge -R Shopify/cli --merge --admin`), with no review; then the same Version Packages steps follow. ## Further reading diff --git a/TORRENT_WORKFLOW.md b/TORRENT_WORKFLOW.md index 3dfbc2a12e9..7bb73a2b0b7 100644 --- a/TORRENT_WORKFLOW.md +++ b/TORRENT_WORKFLOW.md @@ -18,8 +18,10 @@ work. The task statement governs _what_ to build. `main` branch changes only through the mirror's pull requests. Code changes are made upstream and mirrored here, so don't open a PR into `main` for them. PRs into this repository are only for the files the mirror doesn't manage (`.github`, `.spin`, `dev.yml`, `TORRENT_WORKFLOW.md`, `AGENTS.md`, -`.agents`, `.claude` and `.cursor`) and for `stable/*` patch branches. Outside contributors still -open PRs here. +`.agents`, `.claude` and `.cursor`) and for patch backports into `stable/X.Y` release branches. +Outside contributors still open PRs here. Minor and patch releases ship from `stable/X.Y`. While +a release is open, only its release owner merges into that branch; anyone else, agents included, +asks the release owner first. A dispatched session reads this file as its instructions say: the `` block, or `torrent worker workflow `. A human-directed session reads it with @@ -184,7 +186,7 @@ memory and the human's window into your progress. `torrent help` lists the `work - Open: `torrent github pr open --draft --base main --title "" --body-file <file>`. Always name the base: without `--base`, the command opens the PR into `main`. Use `main` only - for the files the mirror doesn't manage, and `stable/X.Y` for a patch. + for the files the mirror doesn't manage, and `stable/X.Y` for a patch backport. - Link: `torrent link add <id> https://github.com/Shopify/cli/pull/<n>`. Torrent does not find or link a GitHub PR by itself. - This repository is public, so also set