Skip to content
Open
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
18 changes: 6 additions & 12 deletions .claude/commands/write_release_descriptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <number> -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 -- <changeset file>` 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:

Expand All @@ -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.

Expand All @@ -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`:
Expand Down
10 changes: 6 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <number> --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 <commit>: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 <number> -R Shopify/cli --merge --admin --match-head-commit <H>`. 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 <number> -R Shopify/cli --merge --admin`), with no review; then the same Version Packages steps follow.

## Further reading

Expand Down
8 changes: 5 additions & 3 deletions TORRENT_WORKFLOW.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<torrent-workflow>` block, or
`torrent worker workflow <session>`. A human-directed session reads it with
Expand Down Expand Up @@ -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 "<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
Expand Down
Loading