Skip to content

Commit bc2abfb

Browse files
committed
feat(release): cut a patch from a release/<major>.<minor> maintenance branch
release.mjs and finish-release.mjs refused any branch but main, so a patch on a line main has moved past could not go through its own guarded scripts. Both now accept release/<major>.<minor> as well (one shared rule in scripts/lib/release-branch.mjs): the version must be on that branch's own line, every push goes to that branch, and finish-release's sync check compares HEAD with origin/<branch>. Every other gate is unchanged. docs/RELEASING.md gains the maintenance-branch section, including that the site deploys from the newest vN.N.N tag wherever it was cut.
1 parent 48e2e88 commit bc2abfb

9 files changed

Lines changed: 203 additions & 17 deletions

‎docs/RELEASING.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -614,6 +614,40 @@ default, so a dispatch meant to report cannot write.
614614
Then verify: `npm dist-tag ls @metaobjectsdev/<pkg>` — authoritative, where `npm view` is
615615
CDN-cached and lags right after publish.
616616
617+
## Patch from a maintenance branch (`release/<major>.<minor>`)
618+
619+
**When.** `main` already holds work for the next minor (or major) that must not ship yet, and a
620+
fix has to go out on the line already released. Cut the patch from a maintenance branch named
621+
exactly `release/<major>.<minor>` (for example `release/1.2`), branched from that line's last
622+
release commit, with the fix merged into it by PR. If `main` has nothing unreleased beyond the
623+
patch, cut from `main` as usual instead.
624+
625+
**What the scripts do differently.** `scripts/release.mjs` and `scripts/finish-release.mjs`
626+
accept `release/<major>.<minor>` as well as `main` (the rule is
627+
[`scripts/lib/release-branch.mjs`](../scripts/lib/release-branch.mjs), shared by both):
628+
629+
- The version must be on the branch's own line: `release/1.2` cuts `1.2.x` (and `1.2.x-rc.N`)
630+
and refuses anything else, such as `1.3.0`.
631+
- Every push goes to that branch (`git push origin release/1.2`), never `main`.
632+
- `finish-release`'s sync check compares HEAD with `origin/release/1.2`, not `origin/main`.
633+
634+
Every other gate is unchanged. Bump the PyPI/NuGet/Maven manifests, run `bun run site:payload`,
635+
commit and push on the maintenance branch, and push the `python-v*` / `csharp-v*` / `java-v*`
636+
tags from it, exactly as on `main`.
637+
638+
**The site follows the newest tag.** The website deploys from the newest `vN.N.N` release tag
639+
(rule 7), wherever it was cut. A patch tag on a maintenance branch therefore becomes what
640+
metaobjects.dev shows, including its payload and coordinates, until the next release is tagged.
641+
The converse is enforced: `finish-release` refuses to tag a patch on a line older than a tag
642+
that already exists (`v1.2.3` once `v1.3.0` exists), because the deploy would never resolve it.
643+
So a maintenance patch is for a line that is still the newest release. The same holds on npm:
644+
`release.mjs` publishes to `latest`, and a patch cut after a newer minor shipped would move
645+
`latest` backwards.
646+
647+
**Then bring the fix to `main`.** A maintenance branch is never merged back wholesale (its
648+
version bumps and CHANGELOG would collide with `main`'s). Cherry-pick or re-land each fix on
649+
`main` by PR.
650+
617651
## Isolated patch (one package)
618652
619653
If only one package changed (e.g. a `cli` bugfix), bump just that package, `rm bun.lock && bun

‎scripts/ci-local.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -487,7 +487,7 @@ gate_site_reference() { bun_install && bun scripts/build-site-reference.ts --che
487487
# exercised) are the ones worth a test at all. See scripts/maven-coordinate.mjs.
488488
# And the publish workflows' tag check (scripts/check-release-tag.mjs), whose test also reads
489489
# each real manifest, so a layout change fails here rather than on a release tag.
490-
gate_release_tag() { bun test scripts/finish-release.test.ts scripts/eject-release-gate.test.ts && node scripts/test-maven-coordinate.mjs && node scripts/test-prerelease-version.mjs && node scripts/test-check-release-tag.mjs && node scripts/test-changelog-promote.mjs && bash tools/prerelease/test-prerelease-link.sh; }
490+
gate_release_tag() { bun test scripts/finish-release.test.ts scripts/eject-release-gate.test.ts && node scripts/test-maven-coordinate.mjs && node scripts/test-prerelease-version.mjs && node scripts/test-check-release-tag.mjs && node scripts/test-changelog-promote.mjs && node scripts/test-release-branch.mjs && bash tools/prerelease/test-prerelease-link.sh; }
491491

492492
# ── repo-root scripts/ typechecks ─────────────────────────────────────────────
493493
# `bun test` transpiles per file and never typechecks, and `bun run --filter '*'

‎scripts/eject-release-gate.test.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -102,9 +102,9 @@ describe("eject release gate — the command and its wiring", () => {
102102

103103
// ADR-0034 Amendment 8 makes the gate the first preflight check of `release.mjs`. The
104104
// check after it is the branch check, so a fixture on another branch tells the two apart:
105-
// a refused version stops before "must be on main", and an allowed one reaches it.
105+
// a refused version stops before "not on main", and an allowed one reaches it.
106106
test("release.mjs asks the gate first in its preflight, and stops on a refusal", () => {
107-
const RELEASE_SCRIPTS = ["release.mjs", "lib/changelog-promote.mjs", "publish-set.mjs", "maven-coordinate.mjs"];
107+
const RELEASE_SCRIPTS = ["release.mjs", "lib/changelog-promote.mjs", "lib/release-branch.mjs", "publish-set.mjs", "maven-coordinate.mjs"];
108108
const onBranch = (pending: (typeof ENTRY)[]) => {
109109
const root = repoWith(JSON.stringify(manifest(pending)), RELEASE_SCRIPTS);
110110
const git = (...args: string[]) => spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
@@ -119,11 +119,11 @@ describe("eject release gate — the command and its wiring", () => {
119119
const refused = release(blocked, "1.1.0");
120120
expect(refused.code).not.toBe(0);
121121
expect(refused.out).toContain("the eject contract does not hold yet");
122-
expect(refused.out).not.toContain("must be on main");
122+
expect(refused.out).not.toContain("not on main");
123123

124124
for (const allowed of [release(blocked, "1.1.0-rc.1"), release(onBranch([]), "1.1.0")]) {
125125
expect(allowed.out).not.toContain("the eject contract does not hold yet");
126-
expect(allowed.out).toContain("must be on main (you are on not-main)");
126+
expect(allowed.out).toContain("not on main or a release/<major>.<minor> maintenance branch (you are on not-main)");
127127
}
128128
});
129129

‎scripts/finish-release.mjs‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ import { dirname, join, resolve } from "node:path";
3737
import { fileURLToPath } from "node:url";
3838
import { mavenVersion } from "./maven-coordinate.mjs";
3939
import { ejectReleaseRefusalAt } from "./eject-release-gate.mjs";
40+
import { releaseBranchRefusal } from "./lib/release-branch.mjs";
4041

4142
const REPO = resolve(dirname(fileURLToPath(import.meta.url)), "..");
4243
const CHECK_ONLY = process.argv.includes("--check");
@@ -80,8 +81,13 @@ ok("eject contract: the pending list is empty");
8081
if (out("git status --porcelain") !== "") {
8182
die("working tree is dirty — commit or stash before tagging, or the tag names a tree you did not review");
8283
}
83-
if (out("git rev-parse --abbrev-ref HEAD") !== "main") die("not on main");
84-
// NOT `|| true`. A swallowed fetch leaves `origin/main` at a STALE remote-tracking ref,
84+
// `main`, or a `release/<major>.<minor>` maintenance branch tagging a version on its own
85+
// line (scripts/lib/release-branch.mjs). The sync check below compares against THAT
86+
// branch's remote, never origin/main.
87+
const branch = out("git rev-parse --abbrev-ref HEAD");
88+
const branchRefusal = releaseBranchRefusal(branch, VERSION);
89+
if (branchRefusal !== null) die(branchRefusal);
90+
// NOT `|| true`. A swallowed fetch leaves `origin/<branch>` at a STALE remote-tracking ref,
8591
// and the very next comparison then prints "synced with origin" having verified nothing —
8692
// with git's own "Could not read from remote repository" scrolling past just above the
8793
// tick. The realistic case is the port-bump commit pushed from another checkout while
@@ -93,10 +99,12 @@ try {
9399
die(`git fetch origin failed, so "synced with origin" cannot be verified: ` +
94100
`${e instanceof Error ? e.message : String(e)}`);
95101
}
96-
if (out("git rev-parse HEAD") !== out("git rev-parse origin/main")) {
97-
die("HEAD is not origin/main — push first; the deploy clones the REMOTE tag");
102+
// `|| true` here is not the swallow warned about above: a maintenance branch that was
103+
// never pushed has no `origin/<branch>`, and that must read as "not synced", not crash.
104+
if (out("git rev-parse HEAD") !== out(`git rev-parse --verify --quiet origin/${branch} || true`)) {
105+
die(`HEAD is not origin/${branch} — push first; the deploy clones the REMOTE tag`);
98106
}
99-
ok("on main, clean, synced with origin");
107+
ok(`on ${branch}, clean, synced with origin`);
100108

101109
// ── 2. the tag is free ───────────────────────────────────────────────────────
102110
// Never move a tag. A moved tag silently changes what the website deploys, and any

‎scripts/finish-release.test.ts‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ const SCRIPT = readFileSync(resolve(REPO, "scripts/finish-release.mjs"), "utf8")
3636
const MAVEN_COORD = readFileSync(resolve(REPO, "scripts/maven-coordinate.mjs"), "utf8");
3737
// Gate 0 asks the eject release gate, and the fixture ships the real one for the same reason.
3838
const EJECT_GATE = readFileSync(resolve(REPO, "scripts/eject-release-gate.mjs"), "utf8");
39+
// Gate 1's branch rule, shared with release.mjs — the real module, for the same reason.
40+
const RELEASE_BRANCH = readFileSync(resolve(REPO, "scripts/lib/release-branch.mjs"), "utf8");
3941
const EJECT_MANIFEST = "fixtures/generator-registry-conformance/registry.json";
4042
/** The shared file as the release branch leaves it: nothing pending. */
4143
const EJECT_CLEAR = `${JSON.stringify({ eject: { pending: [] } })}\n`;
@@ -173,6 +175,7 @@ function makeRepo(spec: Spec = {}): Fixture {
173175
"scripts/finish-release.mjs": SCRIPT,
174176
"scripts/maven-coordinate.mjs": MAVEN_COORD,
175177
"scripts/eject-release-gate.mjs": EJECT_GATE,
178+
"scripts/lib/release-branch.mjs": RELEASE_BRANCH,
176179
})) {
177180
const full = join(work, rel);
178181
mkdirSync(dirname(full), { recursive: true });
@@ -291,6 +294,46 @@ describe("finish-release gate 1: the tree that will be tagged", () => {
291294
expect(r.out).toContain("HEAD is not origin/main");
292295
});
293296

297+
// A maintenance branch `release/<major>.<minor>` may tag a patch on its own line; the
298+
// rule itself is unit-tested in scripts/test-release-branch.mjs. These cases prove the
299+
// script wires it: the branch is accepted, a version off its line is refused, and the
300+
// sync check compares against origin/<that branch>, never origin/main.
301+
const onMaintenance = (name: string, push = true) => {
302+
const f = makeRepo();
303+
f.git(f.work, "checkout", "--quiet", "-b", name);
304+
if (push) f.git(f.work, "push", "--quiet", "-u", "origin", name);
305+
return f;
306+
};
307+
308+
test("a maintenance branch on the release's own line passes gate 1", () => {
309+
const r = onMaintenance("release/0.24").run(RELEASE, "--check");
310+
expect(r.out).toContain("on release/0.24, clean, synced with origin");
311+
expect(r.code).toBe(0);
312+
});
313+
314+
test("a maintenance branch refuses a version off its line", () => {
315+
const r = onMaintenance("release/0.23").run(RELEASE, "--check");
316+
expect(r.code).not.toBe(0);
317+
expect(r.out).toContain("cuts only 0.23.x");
318+
expect(r.out).not.toContain("synced with origin");
319+
});
320+
321+
test("a maintenance branch syncs against its OWN remote, not origin/main", () => {
322+
const f = onMaintenance("release/0.24");
323+
writeFileSync(join(f.work, "NOTES.md"), "unpushed\n");
324+
f.git(f.work, "add", "-A");
325+
f.git(f.work, "commit", "--quiet", "-m", "local only");
326+
const r = f.run(RELEASE, "--check");
327+
expect(r.code).not.toBe(0);
328+
expect(r.out).toContain("HEAD is not origin/release/0.24");
329+
});
330+
331+
test("a maintenance branch never pushed is refused, not crashed on", () => {
332+
const r = onMaintenance("release/0.24", false).run(RELEASE, "--check");
333+
expect(r.code).not.toBe(0);
334+
expect(r.out).toContain("HEAD is not origin/release/0.24");
335+
});
336+
294337
// The defect: the fetch was `|| true`, so a failure left `origin/main` at a stale
295338
// remote-tracking ref and the very next line printed "synced with origin" having
296339
// verified nothing. The realistic case is the port-bump commit pushed from another
@@ -647,6 +690,21 @@ describe("finish-release gate 7: cutting the tag", () => {
647690
expect(f.git(f.origin, "tag", "-l")).toContain(`v${RELEASE}`);
648691
});
649692

693+
test("tags and pushes from a maintenance branch, leaving origin/main where it was", () => {
694+
const f = makeRepo();
695+
const mainBefore = f.git(f.origin, "rev-parse", "main");
696+
f.git(f.work, "checkout", "--quiet", "-b", "release/0.24");
697+
writeFileSync(join(f.work, "NOTES.md"), "the patch\n");
698+
f.git(f.work, "add", "-A");
699+
f.git(f.work, "commit", "--quiet", "-m", "patch on the maintenance line");
700+
f.git(f.work, "push", "--quiet", "-u", "origin", "release/0.24");
701+
const r = f.run(RELEASE);
702+
expect(r.out).toContain(`cut and pushed v${RELEASE}`);
703+
expect(r.code).toBe(0);
704+
expect(f.git(f.origin, "rev-parse", `v${RELEASE}^{commit}`)).toBe(f.git(f.work, "rev-parse", "HEAD"));
705+
expect(f.git(f.origin, "rev-parse", "main")).toBe(mainBefore);
706+
});
707+
650708
test("--check cuts nothing", () => {
651709
const f = makeRepo();
652710
expect(f.run(RELEASE, "--check").code).toBe(0);

‎scripts/lib/release-branch.mjs‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Which branch a release may be cut from — shared by `scripts/release.mjs` and
2+
// `scripts/finish-release.mjs`, so the two cannot disagree about it.
3+
//
4+
// Two kinds of branch qualify:
5+
//
6+
// - `main`, for every release, as before.
7+
// - a maintenance branch named `release/<major>.<minor>`, for a PATCH on a line `main`
8+
// has moved past. It may cut only versions on its own line: `release/1.2` cuts 1.2.x
9+
// and nothing else, because a 1.3.0 cut from it would ship a minor without the work
10+
// `main` holds for that minor.
11+
//
12+
// The caller pushes to, and compares HEAD against, `origin/<branch>` — never `origin/main`
13+
// when it is on a maintenance branch.
14+
15+
/** The pattern a maintenance branch name must match. */
16+
export const MAINTENANCE_BRANCH = /^release\/(\d+)\.(\d+)$/;
17+
18+
/**
19+
* Why `version` may not be released from `branch`, or `null` when it may.
20+
*
21+
* @param {string} branch the current branch, as `git rev-parse --abbrev-ref HEAD` prints it
22+
* @param {string} version the version being cut (`1.2.2`, or `1.2.2-rc.1` for release.mjs)
23+
* @returns {string | null}
24+
*/
25+
export function releaseBranchRefusal(branch, version) {
26+
if (branch === "main") return null;
27+
const m = MAINTENANCE_BRANCH.exec(branch);
28+
if (m === null) {
29+
return `not on main or a release/<major>.<minor> maintenance branch (you are on ${branch})`;
30+
}
31+
const [, major, minor] = m;
32+
const v = /^(\d+)\.(\d+)\./.exec(version);
33+
if (v === null || v[1] !== major || v[2] !== minor) {
34+
return `${branch} is the ${major}.${minor} maintenance branch and cuts only ${major}.${minor}.x — ` +
35+
`${version} is not on that line (cut it from main, or from its own release/<major>.<minor>)`;
36+
}
37+
return null;
38+
}

‎scripts/release.mjs‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ import { createInterface } from "node:readline/promises";
3333
import { publishSet } from "./publish-set.mjs";
3434
import { mavenVersion } from "./maven-coordinate.mjs";
3535
import { ejectReleaseRefusalAt } from "./eject-release-gate.mjs";
36+
import { releaseBranchRefusal } from "./lib/release-branch.mjs";
3637

3738
const VERSION = process.argv[2];
3839
const DRY = process.argv.includes("--dry-run");
@@ -70,10 +71,14 @@ console.log(`\n── Releasing ${VERSION}${DRY ? " (DRY RUN)" : ""} ──\n`)
7071
const ejectRefusal = ejectReleaseRefusalAt(VERSION, join(dirname(fileURLToPath(import.meta.url)), ".."));
7172
if (ejectRefusal !== null) die(ejectRefusal);
7273

74+
// `main`, or a `release/<major>.<minor>` maintenance branch cutting a version on its own
75+
// line (scripts/lib/release-branch.mjs). Everything below that pushes or compares against
76+
// the remote uses THIS branch, so a maintenance cut never touches main.
7377
const branch = out("git rev-parse --abbrev-ref HEAD");
74-
if (branch !== "main") die(`must be on main (you are on ${branch})`);
78+
const branchRefusal = releaseBranchRefusal(branch, VERSION);
79+
if (branchRefusal !== null) die(branchRefusal);
7580
sh("git fetch origin", { quiet: true });
76-
if (out("git rev-list --count HEAD..origin/main") !== "0") die("main is behind origin/main — pull first");
81+
if (out(`git rev-list --count HEAD..origin/${branch}`) !== "0") die(`${branch} is behind origin/${branch} — pull first`);
7782

7883
// Clean tree, except the CHANGELOG (we promote its [Unreleased] section) and untracked noise.
7984
const dirty = out("git status --porcelain").split("\n")
@@ -129,7 +134,7 @@ const taken = (await Promise.all(set.map(async (p) => {
129134
if (taken.length)
130135
die(`${VERSION} is already published for:\n ${taken.join("\n ")}\n` +
131136
`npm versions are permanent — pick the next free version.`);
132-
ok(`preflight: on main, synced, ${VERSION} free on all ${set.length} packages`);
137+
ok(`preflight: on ${branch}, synced, ${VERSION} free on all ${set.length} packages`);
133138
ok(`lockstep set @ ${current}: ${set.length} packages → ${VERSION}`);
134139

135140
// The showcase corpus is what metaobjects.dev publishes as "real `meta gen` output",
@@ -262,7 +267,7 @@ for (const pkg of ordered) {
262267

263268
// --- PHASE 8: push (the tag is NOT cut here) -------------------------------
264269
// This script publishes npm, which is one of FOUR registries. The PyPI/NuGet/Maven
265-
// version bump is a separate, later commit — so at this point `main` states the new npm
270+
// version bump is a separate, later commit — so at this point the branch states the new npm
266271
// coordinate and three stale ones, and the site payload committed above says exactly
267272
// that.
268273
//
@@ -274,8 +279,8 @@ for (const pkg of ordered) {
274279
//
275280
// So the tag moves to the END of the coordinated cut: `scripts/finish-release.mjs`,
276281
// which refuses to tag until the payload's coordinates match what actually shipped.
277-
sh("git push origin main", { quiet: true });
278-
ok("pushed main (tag deferred to finish-release)");
282+
sh(`git push origin ${branch}`, { quiet: true });
283+
ok(`pushed ${branch} (tag deferred to finish-release)`);
279284

280285
// --- PHASE 11: post-publish smoke (the RC's safety net) -------------------
281286
// NOT under tmpdir(). Node's resolution walks UP from the scratch dir, so a stale
@@ -299,4 +304,4 @@ console.log(` 3. \`bun scripts/finish-release.mjs ${VERSION}\` — gates the c
299304
console.log(` The website pins to v${VERSION}, so tagging before step 1 publishes three stale versions.`);
300305
console.log(` Docs version refs are NOT auto-bumped (low-value churn for a patch); batch them when convenient.`);
301306
console.log(` The site payload IS auto-bumped and committed here — but only its npm coordinate.`);
302-
console.log(` The PyPI/NuGet/Maven bump commit must run \`bun run site:payload\` or gates goes red on main.\n`);
307+
console.log(` The PyPI/NuGet/Maven bump commit must run \`bun run site:payload\` or gates goes red on ${branch}.\n`);

0 commit comments

Comments
 (0)