diff --git a/scripts/branch.sh b/scripts/branch.sh index 7c65eee..19d394a 100755 --- a/scripts/branch.sh +++ b/scripts/branch.sh @@ -4,43 +4,13 @@ set -eu # Branch front-door. Run as `npm run create:branch -- /`. # -# How we got here (short): the branching model says every change starts from a -# clean, current `main`, and the type-driven loop only produces trustworthy -# results if the baseline was green *before* the first edit. Both facts were -# prose. Prose rots silently — a rule nobody checks is a suggestion — so the -# precondition became this script: it asserts, then branches, and the branch -# only appears if the assertions passed. Cheap checks run first, `npm run test` -# runs last: the expensive gate is not paid on a tree that was never eligible. +# Asserts the branch preconditions — clean tree, no in-progress operation, +# current `main`, green baseline — and only then creates the branch, so the +# expensive `npm run test` is not paid on a tree that was never eligible. # -# Rejected for the prefix name: `run:` / `perform:` (both mean only "do the -# thing named after them", so every script in the repo would fit under them and -# the taxonomy collapses); `git:` (names the tool, not the lifecycle moment, and -# advertises passthrough aliases); `start:` (describes this half, not the -# release); `cut:` (idiomatic for both, but it needs VCS slang to decode, and a -# signpost that has to be explained is not one); `flow:` (overloaded in a library -# about type-level matching); and the existing families — `check:*` is read-only -# and aggregated by `check`, so CI would run a command that mutates repo state; -# `fix:*`'s review surface is a file diff, not a branch; `maintain:*` is advisory -# and explicitly never a gate. -# -# `create:` was kept because both members really do create something: a branch, -# a release. It was added to both prefix lists in CONTRIBUTING.md in the same -# commit as its first members, because a prefix missing from those lists is -# invisible — which was the `use:` mistake this repo carried in backlog.tasks (since retired into `setup:`). -# There is deliberately no bare `create` aggregator: "run all the workflows" -# describes nothing anyone wants, and `publish:*` already sets the precedent for -# a prefix without one. -# -# Also rejected here: reusing `pubv`'s preflight (release-shaped, third-party, -# and it would make branch start pay a build + pack it has no use for). The -# merge half was originally rejected too ("review the diff yourself" is -# judgment), but it now has its own front door — `create:finish` — which owns -# the merge-side preconditions and the post-merge `verify`, so the start half -# does not have to carry that burden. -# -# Every refusal is non-mutating except the baseline test, which runs on `main` -# after we switch there — so a red `main` restores the branch you started on -# rather than stranding you on it. +# Why the front door exists, the rejected prefix names, and the `create:` +# decision: development/workflow.md § Branching model and § Script prefix +# convention. BASE="main" PREFIXES="feature fix chore" diff --git a/scripts/finish.sh b/scripts/finish.sh index 2ac6b9f..f3e40f0 100755 --- a/scripts/finish.sh +++ b/scripts/finish.sh @@ -4,29 +4,14 @@ set -eu # Feature-finish front door. Run as `npm run create:finish`. # -# Why this exists: `create:branch` opens a unit of work, but the close half -# (`git checkout main && git merge --no-ff `) stayed prose in the -# branching model, so it drifted per contributor and per session. This is the -# mirror image of `create:branch`: it asserts the same preconditions (clean -# tree, no in-progress operation, `main` matching its upstream), merges the -# current `feature/`/`fix/`/`chore/` branch into `main`, proves the result with -# `npm run verify`, and only then deletes the branch. +# Mirror image of `create:branch`: asserts the merge-side preconditions, merges +# the current `feature/`/`fix/`/`chore/` branch into `main` with `--no-ff`, +# proves the result with `npm run verify`, and only then deletes the branch. The +# push is owned by `create:release`, so the merge stays local and reviewable. +# On a conflict it aborts and returns to the feature branch. # -# `create:branch`'s comment argued against wrapping the merge as "judgment — -# review the diff yourself". That judgment still lives here, just moved: the -# maintainer reviews the handover *before* invoking this, and the script only -# commits the merge, never the push. The push is owned by `create:release`, so -# the release commit and its tag leave together and a local merge stays -# reviewable (and can be reverted with `git revert -m 1`) until then. `--no-ff` -# keeps the unit of work visible in `git log`. -# -# Unlike `create:branch` a stale `main` is fast-forwarded instead of refused: -# the tree is clean (checked above) and `main` is not the checked-out branch -# yet, so there is no local state to lose. True divergence (local commits *and* -# upstream commits) is still refused — that needs a human. -# -# On a merge conflict we abort and return to the feature branch, so a failed -# finish never strands you on a half-merged `main`. +# Rationale and the rejected alternatives: development/workflow.md § Branching +# model. BASE="main" PREFIXES="feature fix chore" diff --git a/scripts/precompress.ts b/scripts/precompress.ts index 2327a01..4ff1794 100644 --- a/scripts/precompress.ts +++ b/scripts/precompress.ts @@ -9,6 +9,9 @@ import zlib from "node:zlib"; * matching `Accept-Encoding` and falls back to the original for the rest. * * Usage: node --strip-types scripts/precompress.ts [...] + * + * Why sidecars rather than per-request compression: development/ci.md § Coverage + * serving. */ /** diff --git a/scripts/release-notes.sh b/scripts/release-notes.sh index 64540fa..8c39a24 100755 --- a/scripts/release-notes.sh +++ b/scripts/release-notes.sh @@ -9,6 +9,8 @@ set -eu # `v1.2.3` and `1.2.3` match the `## [1.2.3]` heading. Prints to stdout and # exits non-zero when the tag has no section, so a release can never publish # with an empty body. +# +# Why: development/publishing.md § Release notes are extracted from the changelog. TAG="${1:-}" CHANGELOG="${CHANGELOG:-CHANGELOG.md}" diff --git a/scripts/release.sh b/scripts/release.sh index b8ec2a3..c24092f 100755 --- a/scripts/release.sh +++ b/scripts/release.sh @@ -4,29 +4,13 @@ set -eu # Release front-door. Run as `npm run create:release`. # -# How we got here (short): we want hand-written Keep-a-Changelog notes, an -# [Unreleased] -> "## [x.y.z] - DATE" graduation, and a tag that marks the exact -# commit on main that gets published. No single tool did BOTH the [Unreleased] -# graduation AND the package.json bump. So split by strength: `pubv` (tiny, -# changelog-driven) owns preflight + the interactive major/minor/patch heuristic -# + graduating/committing CHANGELOG.md (no tag, no push); `npm version` syncs -# package.json + the lockfile; `--amend` folds them into pubv's single commit; -# tag AFTER the amend (so the tag is never orphaned) and push. +# Graduates the [Unreleased] changelog notes, bumps package.json + the lockfile, +# and commits then tags the exact SHA that CI publishes. The notes are finalized +# in VS Code before pubv because pubv's bump heuristic reads the [Unreleased] +# body. # -# The notes are finalized in VS Code *before* pubv: the [Unreleased] body is -# what pubv's bump heuristic reads, so editing afterwards would inform the -# changelog only, not the version choice. pubv refuses a dirty tree, so that -# edit is committed as a staging commit and folded back into the single release -# commit below. -# -# Rejected: the conventional-commits family (our history is gitmoji, not -# Conventional; and we want hand-written notes); changesets/rtk (config + a -# heavier version/publish flow that fights our CI-only publish); knope/kacl/ -# bestikk (changelog-only — don't bump package.json; plus 5yr/2yr/brand-new -# maintenance); pubv alone (verified it never writes package.json). We also -# tried `versions` (silverwind) — great Gitea support — but pairing it with a -# hand-rolled promote became a ~180-line script we'd have to maintain, which is -# exactly what this ~30-line version replaces. +# Tooling rationale, the rejected alternatives, and the version source of truth: +# development/publishing.md. CHANGELOG="CHANGELOG.md" BASE="main" diff --git a/scripts/runner-image.sh b/scripts/runner-image.sh index 6205cbd..ccab054 100755 --- a/scripts/runner-image.sh +++ b/scripts/runner-image.sh @@ -8,6 +8,9 @@ set -euo pipefail # pulls the image by name. # # Usage: scripts/runner-image.sh [--push] +# +# Why the image is baked, its two invariants, and the coordinated Node-bump +# steps: development/ci.md. IMAGE_REPO="gitea.e1nsnull.de/tmu/act-ci"