Prepare semver support

.github/PULL_REQUEST_TEMPLATE.md

@@ -3,15 +3,15 @@
   - Prefix it with [Feature] (if applicable)
   - Start with a verb, for example: Add, Delete, Improve, Fix…
   - Give as much context as necessary and as little as possible
-  - Use a draft PR while it’s a work in progress
+  - Use a draft PR while it's a work in progress
 -->
 
 ### WHY are these changes introduced?
 
 Fixes #0000 <!-- link to issue if one exists -->
 
 <!--
-  Context about the problem that’s being addressed.
+  Context about the problem that's being addressed.
 -->
 
 ### WHAT is this pull request doing?
@@ -40,5 +40,5 @@ Fixes #0000 <!-- link to issue if one exists -->
 
 - [ ] I've considered possible cross-platform impacts (Mac, Linux, Windows)
 - [ ] I've considered possible [documentation](https://shopify.dev) changes
-- [ ] I've considered analytics changes to measure impact
-- [ ] The change is user-facing, so I've added a changelog entry with `pnpm changeset add`
+- [ ] I've considered analytics changes to measure impact
+- [ ] The change is user-facing — I've identified the correct bump type (`patch` for bug fixes · `minor` for new features · `major` for [breaking changes](../CONTRIBUTING.md#what-counts-as-a-breaking-change)) and added a changeset with `pnpm changeset add`

.github/workflows/release.yml

@@ -10,7 +10,7 @@ on:
   push:
     branches:
       - main
-      - stable/3.*
+      - stable/*
 
   # Trigger for manual/cron release functionality
   schedule:

.github/workflows/tests-main.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches:
       - main
-      - stable/3.*
+      - stable/*
     paths-ignore:
       - '**.md'
       - 'docs/**'

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to Shopify CLI
+
+## Changesets and versioning
+
+This project uses [Changesets](https://github.com/changesets/changesets) to manage versions and changelogs. Every user-facing change requires a changeset file.
+
+```
+pnpm changeset add
+```
+
+### Choosing the right bump type
+
+The CLI follows [semantic versioning](https://semver.org). Pick the bump type that matches the nature of your change:
+
+| Bump | When to use |
+| :---- | :---- |
+| `patch` | Bug fix that doesn't change any public interface |
+| `minor` | New feature or behaviour that is backwards-compatible |
+| `major` | Breaking change to a stable interface (see table below) |
+
+### What counts as a breaking change
+
+The following interfaces are **stable** — any incompatible change to them requires a `major` bump:
+
+| Interface | Breaking change examples |
+| :---- | :---- |
+| **Command surface** | Removing a command or subcommand; renaming a flag; changing a flag's semantics |
+| **Exit codes** | Changing the exit code for a given outcome |
+| **Machine-readable output (`--json`)** | Removing or renaming a JSON key; changing a value's type |
+| **Config file schema** (`shopify.app.toml`, etc.) | Removing a required key; changing a key's type |
+| **Extension manifest schema** | Removing a field; changing validation rules that reject previously-valid manifests |
+| **`@shopify/cli-kit` public API** | Removing or renaming a publicly exported function or type |
+| **Documented environment variables** | Removing or renaming a documented env var |
+
+Human-readable output (messages, spinner text, prompts) is **not** a stable interface. Changing wording or formatting is not a breaking change.
+
+### Deprecation policy
+
+Before removing or incompatibly changing a stable interface:
+
+1. Mark it deprecated in the code and surface a runtime warning when it is used.
+2. Ship the deprecation notice in a **minor** release — this starts the clock.
+3. Wait at least one minor release cycle before removing it.
+4. Ship the removal in a **major** release with a migration guide in the release notes.

bin/create-homebrew-pr.js

@@ -40,11 +40,16 @@ program
     if (options.openPr) {
       console.log(`Opening a PR in shopify/homebrew-shopify to update the formula ${version}`)
 
+      const majorVersion = parseInt(version.split('.')[0], 10)
       const files = {}
       switch (templateVersion) {
-        case "3":
+        case "stable":
           files["shopify-cli.rb"] = (await readFile(path.join(outputDirectory, "shopify-cli.rb"))).toString()
-          files["shopify-cli@3.rb"] = (await readFile(path.join(outputDirectory, "shopify-cli@3.rb"))).toString()
+          // Only keep the @3 versioned formula up to date while we are on major version 3.
+          // Once we move to v4+, shopify-cli@3.rb stays frozen at the last 3.x release.
+          if (majorVersion === 3) {
+            files["shopify-cli@3.rb"] = (await readFile(path.join(outputDirectory, "shopify-cli@3.rb"))).toString()
+          }
           break
         case "pre":
           files["shopify-cli-pre.rb"] = (await readFile(path.join(outputDirectory, "shopify-cli-pre.rb"))).toString()
@@ -70,7 +75,7 @@ program
           changes: [
             {
               files,
-              commit: `Update Shopify CLI 3 formula to install the version ${version}`,
+              commit: `Update Shopify CLI formula to install version ${version}`,
             },
           ],
           createWhenEmpty: false,
@@ -106,7 +111,7 @@ async function versionToRelease() {
 function getTemplateVersion(version) {
   if (version.includes("pre")) return "pre"
   if (version.includes("nightly")) return "nightly"
-  if (version.match(/^3\.\d+\.\d+$/)) return "3"
+  if (version.match(/^\d+\.\d+\.\d+$/)) return "stable"
   throw `Unrecognized version string ${version}`
 }
 

packaging/nightly/src/shopify-cli-nightly.rb.liquid

@@ -1,4 +1,4 @@
-{% render '3/src/shopify-cli.rb.liquid',
+{% render 'stable/src/shopify-cli.rb.liquid',
           formulaVersion: 'nightly',
           cliTarball: cliTarball,
           cliSha: cliSha,

packaging/3/src/shopify-cli@3.rb.liquid → packaging/stable/src/shopify-cli@3.rb.liquid

@@ -1,4 +1,4 @@
-{% render '3/src/shopify-cli.rb.liquid',
+{% render 'stable/src/shopify-cli.rb.liquid',
           formulaVersion: '3',
           cliTarball: cliTarball,
           cliSha: cliSha,