From 9aa9da2d37e2d728c3a0fe261126c68ac68460ee Mon Sep 17 00:00:00 2001 From: Victor Chu Date: Mon, 17 Aug 2026 16:59:49 -0700 Subject: [PATCH 1/3] docs: add calver changeset rules to AGENTS.md Assisted-By: devx/60256637-da58-4f80-9e3a-977e038d8a71 --- AGENTS.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index a20fca7135..2566bd806d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,6 +7,23 @@ After every change, you must: 3. **Check for type errors** — run the TypeScript compiler to verify there are no type errors. 4. **Check for lint and formatting errors** — run the linter and formatter to ensure code quality. +## Changesets and versioning + +Package versions are **calendar versions**: the `major.minor` of the npm +version *is* the Shopify API version (`2026.10.x` → API version `2026-10`, +derived at build time — see `packages/ui-extensions-tester/src/api-version.ts`). + +- **Never mark a changeset `major`.** A major bump rolls the calendar year + (`2026.10.0` → `2027.0.0` → API version "2027-00", which doesn't exist), + breaks the tester's version check on every PR, and publishes an RC that is + semver-higher than the branch's own final release. Breaking changes are + already gated by API version; declare them `minor` and describe the break in + the changeset text (see #4612 → #4636 for the incident this rule comes from). +- On RC branches (`.changeset/pre.json` present), released changeset files are + **retained** and keep contributing to version computation until pre-mode + exits — correcting a bad version requires fixing the changeset file itself, + not just `package.json`. + ## ui-extensions-tester When working on `ui-extensions-tester`, ALWAYS read [packages/ui-extensions-tester/AGENTS.md](packages/ui-extensions-tester/AGENTS.md). From 063f3658a780a3ce2059c78c8c9b6d89fb246b9e Mon Sep 17 00:00:00 2001 From: Victor Chu Date: Mon, 17 Aug 2026 17:05:17 -0700 Subject: [PATCH 2/3] style: prettier AGENTS.md Assisted-By: devx/60256637-da58-4f80-9e3a-977e038d8a71 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 2566bd806d..40cce65699 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ After every change, you must: ## Changesets and versioning Package versions are **calendar versions**: the `major.minor` of the npm -version *is* the Shopify API version (`2026.10.x` → API version `2026-10`, +version _is_ the Shopify API version (`2026.10.x` → API version `2026-10`, derived at build time — see `packages/ui-extensions-tester/src/api-version.ts`). - **Never mark a changeset `major`.** A major bump rolls the calendar year From 1aa323e4e9bbcce07063893f5d04c6d02fb8115d Mon Sep 17 00:00:00 2001 From: Victor Chu Date: Mon, 17 Aug 2026 17:09:55 -0700 Subject: [PATCH 3/3] docs: drop incident citation Assisted-By: devx/60256637-da58-4f80-9e3a-977e038d8a71 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 40cce65699..99106563c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ derived at build time — see `packages/ui-extensions-tester/src/api-version.ts` breaks the tester's version check on every PR, and publishes an RC that is semver-higher than the branch's own final release. Breaking changes are already gated by API version; declare them `minor` and describe the break in - the changeset text (see #4612 → #4636 for the incident this rule comes from). + the changeset text. - On RC branches (`.changeset/pre.json` present), released changeset files are **retained** and keep contributing to version computation until pre-mode exits — correcting a bad version requires fixing the changeset file itself,