diff --git a/.github/workflows/bun-release-changeset-oidc.yml b/.github/workflows/bun-release-changeset-oidc.yml index c5c8000..404dc26 100644 --- a/.github/workflows/bun-release-changeset-oidc.yml +++ b/.github/workflows/bun-release-changeset-oidc.yml @@ -94,7 +94,7 @@ jobs: - name: Create Release Pull Request or Publish to npm id: changesets - uses: changesets/action@v2.0.0 + uses: changesets/action@v1 with: commit: 'chore: version packages' version: bun run version diff --git a/.github/workflows/bun-release-changeset.yml b/.github/workflows/bun-release-changeset.yml index 066e772..0949dfe 100644 --- a/.github/workflows/bun-release-changeset.yml +++ b/.github/workflows/bun-release-changeset.yml @@ -57,7 +57,7 @@ jobs: - name: Create Release Pull Request or Publish to npm id: changesets - uses: changesets/action@v2.0.0 + uses: changesets/action@v1 with: commit: 'chore: version packages' version: bun run version diff --git a/.github/workflows/pnpm-release-changeset-oidc.yml b/.github/workflows/pnpm-release-changeset-oidc.yml index 4a3106b..3d83905 100644 --- a/.github/workflows/pnpm-release-changeset-oidc.yml +++ b/.github/workflows/pnpm-release-changeset-oidc.yml @@ -71,7 +71,7 @@ jobs: - name: Create Release Pull Request or Publish to npm id: changesets - uses: changesets/action@v2.0.0 + uses: changesets/action@v1 with: commit: 'chore: version packages' version: pnpm run version diff --git a/.github/workflows/pnpm-release-changeset.yml b/.github/workflows/pnpm-release-changeset.yml index 2350009..37b3b50 100644 --- a/.github/workflows/pnpm-release-changeset.yml +++ b/.github/workflows/pnpm-release-changeset.yml @@ -54,7 +54,7 @@ jobs: - name: Create Release Pull Request or Publish to npm id: changesets - uses: changesets/action@v2.0.0 + uses: changesets/action@v1 with: commit: 'chore: version packages' version: pnpm run version diff --git a/.github/workflows/yarn-release-changeset-monorepo.yml b/.github/workflows/yarn-release-changeset-monorepo.yml index 35d97d2..d1e09f5 100644 --- a/.github/workflows/yarn-release-changeset-monorepo.yml +++ b/.github/workflows/yarn-release-changeset-monorepo.yml @@ -23,7 +23,7 @@ jobs: - name: Create Release Pull Request or Publish to npm id: changesets - uses: changesets/action@v2.0.0 + uses: changesets/action@v1 with: commit: 'chore: version packages' version: yarn version diff --git a/.github/workflows/yarn-release-changeset.yml b/.github/workflows/yarn-release-changeset.yml index dd596f7..5706ede 100644 --- a/.github/workflows/yarn-release-changeset.yml +++ b/.github/workflows/yarn-release-changeset.yml @@ -24,7 +24,7 @@ jobs: - name: Create Release Pull Request or Publish to npm id: changesets - uses: changesets/action@v2.0.0 + uses: changesets/action@v1 with: commit: 'chore: version packages' version: yarn version diff --git a/.github/workflows/yarn2-library-release.yml b/.github/workflows/yarn2-library-release.yml index f94cbbb..e175322 100644 --- a/.github/workflows/yarn2-library-release.yml +++ b/.github/workflows/yarn2-library-release.yml @@ -21,7 +21,7 @@ jobs: - name: Create Release Pull Request or Publish to npm id: changesets - uses: changesets/action@v2.0.0 + uses: changesets/action@v1 # with: # # run `yarn` again to update peer dependency refs # version: yarn changeset version && yarn diff --git a/README.md b/README.md index fd55835..11ac116 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,76 @@ Use the workflow templates to create workflows for each repository. +## Versioning + +### Which ref to pin + +**Pin a tag, never `@main`.** For the changesets release workflows, which tag +depends on one thing — the major of `@changesets/cli` in your repo: + +| Your `@changesets/cli` | Pin | Because | +| --- | --- | --- | +| v2 | `@v1` | `*-release-changeset*.yml` uses `changesets/action@v1` | +| v3 | `@v2` | `*-release-changeset*.yml` uses `changesets/action@v2` | + +```yaml +jobs: + release: + uses: unional/.github/.github/workflows/pnpm-release-changeset.yml@v1 +``` + +If you do not use those workflows, either tag works — every other workflow is +byte-identical across the two. + +`v1` and `v2` are *moving* tags, re-pointed forward on each backward-compatible +release within their line and never moved across a breaking change. Pin an exact +version (`@v1.0.0`) if you want a ref that never moves, and accept bumping it by +hand. + +Do **not** pin `@main`: every consumer on it takes every change the instant it +merges, including breaking ones nobody reviewed. + +### Why there are two lines + +`changesets/action` and `@changesets/cli` are strictly paired, and the action +enforces it at runtime: + +| `changesets/action` | works with | inputs | +| --- | --- | --- | +| `v1` | `@changesets/cli` v2 | `version`, `publish`, `commit` | +| `v2` | `@changesets/cli` v3 | `version-script`, `publish-script`, `commit-message` | + +Run v2 against CLI v2 and it aborts: *"Changesets CLI v2 is not supported; use +Changesets action v1 instead."* No single workflow serves both. + +Consumers are split across both majors, so the lines run in parallel rather than +one being a deadline. Eleven consumers of `pnpm-release-changeset.yml` are on CLI +v2 (`@v1`); `monorepo-template` and `stable-context` are on v3 (`@v2`). + +**Branch layout:** `main` is the v1 line; the v2 line lives on `v2.x`. A fix that +applies to both is made on `main` and cherry-picked. When the last consumer +reaches CLI v3, `v2.x` merges down and the v1 line retires. + +### Why this exists + +`.mergify.yml` auto-merges Renovate PRs, so bumps to the actions these workflows +call land on `main` with no human in the loop — and under `@main` they reach +every consumer immediately. That is not hypothetical: `changesets/action` v1 → v2 +was auto-merged and broke the release path of every changesets consumer at once. +Tagging means such a bump lands on `main` and waits until someone cuts a release. + +### Cutting a release + +```sh +git checkout main && git pull +git tag -a v1.0.0 -m "v1.0.0" && git push origin v1.0.0 +gh release create v1.0.0 --generate-notes +git tag -f v1 v1.0.0 && git push -f origin v1 +``` + +Same from `v2.x` with `v2.0.0` / `v2`. Forgetting the last step makes the release +invisible to everyone pinning the alias. + [`.gitignore` for yarn](https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored) ## migrate to yarn PnP