From 29a7c4874b7c9721a57fe27d0004d9cc5fe4a4dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olu=CC=81was=CC=A3e=CC=80yi=CC=81=20S=CC=A3o=CC=81bande?= =?UTF-8?q?=CC=81?= Date: Tue, 20 Oct 2026 05:36:11 +0100 Subject: [PATCH 1/2] docs: record release-time Changesets versioning --- .changeset/release-time-versioning.md | 5 +++++ skills/tech-stack/references/practices/toolchain.md | 9 +++++++++ 2 files changed, 14 insertions(+) create mode 100644 .changeset/release-time-versioning.md diff --git a/.changeset/release-time-versioning.md b/.changeset/release-time-versioning.md new file mode 100644 index 0000000..e94d8fb --- /dev/null +++ b/.changeset/release-time-versioning.md @@ -0,0 +1,5 @@ +--- +"tech-stack": patch +--- + +Record release-time Changesets versioning as the default, including token requirements, dry runs and failure handling. diff --git a/skills/tech-stack/references/practices/toolchain.md b/skills/tech-stack/references/practices/toolchain.md index 747f41d..d05a013 100644 --- a/skills/tech-stack/references/practices/toolchain.md +++ b/skills/tech-stack/references/practices/toolchain.md @@ -10,6 +10,15 @@ setting: `check` (fast core, run by pre-push and CI), `check:full` (database, dr why: when hooks and CI run the same tasks, local and CI checks cannot drift verified: 2026-10-06 · https://mise.jdx.dev/tasks/ +### Changesets release-time versioning — default (over changesets/action's standing version PR: merge it, then release) +setting: a manually dispatched Release workflow runs `changeset version` through the repository's version script, commits `chore: release ` to the default branch with the job token, builds assets, pushes the tag at that commit, creates a draft release, then publishes it. A `dry_run` input writes the planned version and changelog section to the run summary and stops before committing, pushing, building or publishing. +why: one click instead of PR + merge + click; no version PR re-running CI on shared runners after every merge +permissions: the token must be able to push to the default branch. Without blocking protection, the job's `GITHUB_TOKEN` with `contents: write` is enough; if branch protection or rulesets block it, use a GitHub App token allowed to bypass those rules. +learned: pushes made with `GITHUB_TOKEN` do not trigger push workflows, so the version commit gets no CI run from its push. An App token can trigger those workflows. +failure policy: if the default branch moved and the commit push fails, fail before tagging; never force-push. After a failed tag push or publish, ship the next patch instead of retrying the same tag. +cost: no changelog review before publishing beyond the dry run +verified: 2026-10-20 · https://changesets.dev/guide/cli#version · [version PR alternative](https://github.com/changesets/action) · [token permissions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions) · [protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) · [App bypass](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-branch-or-tag-ruleset) · [workflow triggers](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow) · [draft release](https://cli.github.com/manual/gh_release_create) · [publish draft](https://cli.github.com/manual/gh_release_edit) · [push rejection](https://docs.github.com/en/get-started/using-git/dealing-with-non-fast-forward-errors). This date covers the documented mechanics; the workflow order, dry run and failure policy are our choices. + ## Rules - A check that CI runs must exist as a mise task; no CI-only checks. Slow lanes live in `check:full` and CI runs them on demand. - Project scripts are thin wrappers that a mise task calls; they do not install tools. From 4ecec777a902d83ec9827e72314d3987bb2472cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olu=CC=81was=CC=A3e=CC=80yi=CC=81=20S=CC=A3o=CC=81bande?= =?UTF-8?q?=CC=81?= Date: Tue, 20 Oct 2026 05:56:28 +0100 Subject: [PATCH 2/2] docs: trim release-time versioning entry to the entry shape --- skills/tech-stack/references/practices/toolchain.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/skills/tech-stack/references/practices/toolchain.md b/skills/tech-stack/references/practices/toolchain.md index d05a013..992785d 100644 --- a/skills/tech-stack/references/practices/toolchain.md +++ b/skills/tech-stack/references/practices/toolchain.md @@ -10,14 +10,11 @@ setting: `check` (fast core, run by pre-push and CI), `check:full` (database, dr why: when hooks and CI run the same tasks, local and CI checks cannot drift verified: 2026-10-06 · https://mise.jdx.dev/tasks/ -### Changesets release-time versioning — default (over changesets/action's standing version PR: merge it, then release) -setting: a manually dispatched Release workflow runs `changeset version` through the repository's version script, commits `chore: release ` to the default branch with the job token, builds assets, pushes the tag at that commit, creates a draft release, then publishes it. A `dry_run` input writes the planned version and changelog section to the run summary and stops before committing, pushing, building or publishing. -why: one click instead of PR + merge + click; no version PR re-running CI on shared runners after every merge -permissions: the token must be able to push to the default branch. Without blocking protection, the job's `GITHUB_TOKEN` with `contents: write` is enough; if branch protection or rulesets block it, use a GitHub App token allowed to bypass those rules. -learned: pushes made with `GITHUB_TOKEN` do not trigger push workflows, so the version commit gets no CI run from its push. An App token can trigger those workflows. -failure policy: if the default branch moved and the commit push fails, fail before tagging; never force-push. After a failed tag push or publish, ship the next patch instead of retrying the same tag. -cost: no changelog review before publishing beyond the dry run -verified: 2026-10-20 · https://changesets.dev/guide/cli#version · [version PR alternative](https://github.com/changesets/action) · [token permissions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions) · [protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) · [App bypass](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-branch-or-tag-ruleset) · [workflow triggers](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow) · [draft release](https://cli.github.com/manual/gh_release_create) · [publish draft](https://cli.github.com/manual/gh_release_edit) · [push rejection](https://docs.github.com/en/get-started/using-git/dealing-with-non-fast-forward-errors). This date covers the documented mechanics; the workflow order, dry run and failure policy are our choices. +### Changesets release-time versioning — default (over changesets/action's standing version PR) +setting: a manually dispatched Release runs the version script, commits `chore: release ` to the default branch, builds, tags that commit, then publishes; a `dry_run` input writes the planned version and changelog to the run summary and stops. If the push is rejected because the branch moved, fail before tagging. +why: one click instead of PR + merge + click, and no version PR re-running CI after every merge +learned: `GITHUB_TOKEN` with `contents: write` can push only where no protection or ruleset blocks it (otherwise use an App token allowed to bypass), and its pushes trigger no workflows, so the version commit gets no CI run +verified: 2026-10-20 · https://changesets.dev/guide/cli · https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow ## Rules - A check that CI runs must exist as a mise task; no CI-only checks. Slow lanes live in `check:full` and CI runs them on demand.