From 48e2e88f34978e3b705fdb1342a9c5436b37e50c Mon Sep 17 00:00:00 2001 From: Doug Mealing Date: Fri, 13 Nov 2026 18:43:29 -0500 Subject: [PATCH 1/5] fix(csharp): a frozen node's memoized reads are safe across threads MetaData.Cached stored derived reads in a plain Dictionary. A loaded model is shared across threads, so two concurrent first reads of one node could corrupt it, and every later read then threw "Operations that change non-concurrent collections must have exclusive access". The cache is now a ConcurrentDictionary; a racing first read keeps the first stored value. Brought onto release/1.2 from main's fix (a266a51c7) for the 1.2.2 patch. --- CHANGELOG.md | 10 ++++ .../CachedReadConcurrencyTests.cs | 47 +++++++++++++++++++ server/csharp/MetaObjects/Meta/MetaData.cs | 9 ++-- 3 files changed, 63 insertions(+), 3 deletions(-) create mode 100644 server/csharp/MetaObjects.Conformance.Tests/CachedReadConcurrencyTests.cs diff --git a/CHANGELOG.md b/CHANGELOG.md index b81c89d1c..65ea81188 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -56,6 +56,16 @@ file changes. No vocabulary or `metamodelVersion` change._ dropping it (nothing is stored); its runner skips that one scenario, recorded in the Python codegen `KNOWN_GAPS.md`. +### Fixed + +- **C#: concurrent reads of a loaded model no longer corrupt its cache.** `MetaData.Cached` + memoized derived reads (`Validators()`, `ResolvedIsArray()`, `OwnAttrs()`, …) in a plain + `Dictionary`, so two threads touching a frozen node for the first time could corrupt it, and + every later read in the process then failed with "Operations that change non-concurrent + collections must have exclusive access". A host that loads metadata once and serves requests + from it in parallel, or a parallel test run, hit this. The cache is now a + `ConcurrentDictionary`. + ## [1.2.1] — Python only _PyPI `1.2.1` only. npm, NuGet and Maven Central stay at `1.2.0` (`8.2.0`): none of them has a diff --git a/server/csharp/MetaObjects.Conformance.Tests/CachedReadConcurrencyTests.cs b/server/csharp/MetaObjects.Conformance.Tests/CachedReadConcurrencyTests.cs new file mode 100644 index 000000000..83f5ed87e --- /dev/null +++ b/server/csharp/MetaObjects.Conformance.Tests/CachedReadConcurrencyTests.cs @@ -0,0 +1,47 @@ +using MetaObjects; +using MetaObjects.Meta; +using Xunit; + +namespace MetaObjects.Conformance.Tests; + +/// +/// A frozen tree is shared across threads (a host loads metadata once and serves every request +/// from it), so the first concurrent touch of a node's memoized reads must not corrupt its cache. +/// +public class CachedReadConcurrencyTests +{ + [Fact] + public void Concurrent_first_reads_of_a_frozen_node_do_not_corrupt_its_cache() + { + for (var round = 0; round < 200; round++) + { + var entity = new MetaObject(new TypeId("object", "entity"), "Order"); + for (var i = 0; i < 40; i++) + { + var f = new MetaField(new TypeId("field", "string"), $"f{i}"); + f.AddChild(new MetaRequiredValidator(new TypeId("validator", "required"), "req")); + entity.AddChild(f); + } + entity.Freeze(); + var fields = entity.OwnFields(); + + using var start = new ManualResetEventSlim(false); + var workers = Enumerable.Range(0, 8).Select(w => Task.Run(() => + { + start.Wait(); + foreach (var f in fields) + { + _ = f.Validators(); + _ = f.ResolvedIsArray(); + _ = f.OwnAttrs(); + _ = f.IsRequired; + } + _ = entity.Fields(); + })).ToArray(); + start.Set(); + Task.WaitAll(workers); + + Assert.All(fields, f => Assert.Single(f.Validators())); + } + } +} diff --git a/server/csharp/MetaObjects/Meta/MetaData.cs b/server/csharp/MetaObjects/Meta/MetaData.cs index f4a86651f..8f9c08624 100644 --- a/server/csharp/MetaObjects/Meta/MetaData.cs +++ b/server/csharp/MetaObjects/Meta/MetaData.cs @@ -150,7 +150,9 @@ public void SetCanonicalAttr(string name, object? canonical) private ErrorSource _source = CodeSource.Default; /// Per-instance read cache: only populated once the node is frozen. - private readonly Dictionary _cache = new(); + // Concurrent: a frozen tree is shared across threads (loaded once, read by every request + // or test), and a plain Dictionary corrupts on two concurrent first writes. + private readonly System.Collections.Concurrent.ConcurrentDictionary _cache = new(); // --------------------------------------------------------------------------- // Constructor @@ -179,8 +181,9 @@ protected T Cached(string key, Func compute) return (T)cached!; } T value = compute(); - if (_frozen) _cache[key] = value; - return value; + // A racing first read computes the same value from the same immutable tree; keep the + // first one stored so every caller gets one instance. + return _frozen ? (T)_cache.GetOrAdd(key, value)! : value; } // --------------------------------------------------------------------------- From bc2abfbfc3ca2947caaf7e3f6895c711f8f07c17 Mon Sep 17 00:00:00 2001 From: Doug Mealing Date: Fri, 13 Nov 2026 18:43:29 -0500 Subject: [PATCH 2/5] feat(release): cut a patch from a release/. 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/. 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/. 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. --- docs/RELEASING.md | 34 ++++++++++++++++++ scripts/ci-local.sh | 2 +- scripts/eject-release-gate.test.ts | 8 ++--- scripts/finish-release.mjs | 18 +++++++--- scripts/finish-release.test.ts | 58 ++++++++++++++++++++++++++++++ scripts/lib/release-branch.mjs | 38 ++++++++++++++++++++ scripts/release.mjs | 19 ++++++---- scripts/test-release-branch.mjs | 42 ++++++++++++++++++++++ tsconfig.scripts.json | 1 + 9 files changed, 203 insertions(+), 17 deletions(-) create mode 100644 scripts/lib/release-branch.mjs create mode 100644 scripts/test-release-branch.mjs diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 5028ef3db..857d4e326 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -614,6 +614,40 @@ default, so a dispatch meant to report cannot write. Then verify: `npm dist-tag ls @metaobjectsdev/` — authoritative, where `npm view` is CDN-cached and lags right after publish. +## Patch from a maintenance branch (`release/.`) + +**When.** `main` already holds work for the next minor (or major) that must not ship yet, and a +fix has to go out on the line already released. Cut the patch from a maintenance branch named +exactly `release/.` (for example `release/1.2`), branched from that line's last +release commit, with the fix merged into it by PR. If `main` has nothing unreleased beyond the +patch, cut from `main` as usual instead. + +**What the scripts do differently.** `scripts/release.mjs` and `scripts/finish-release.mjs` +accept `release/.` as well as `main` (the rule is +[`scripts/lib/release-branch.mjs`](../scripts/lib/release-branch.mjs), shared by both): + +- The version must be on the branch's own line: `release/1.2` cuts `1.2.x` (and `1.2.x-rc.N`) + and refuses anything else, such as `1.3.0`. +- Every push goes to that branch (`git push origin release/1.2`), never `main`. +- `finish-release`'s sync check compares HEAD with `origin/release/1.2`, not `origin/main`. + +Every other gate is unchanged. Bump the PyPI/NuGet/Maven manifests, run `bun run site:payload`, +commit and push on the maintenance branch, and push the `python-v*` / `csharp-v*` / `java-v*` +tags from it, exactly as on `main`. + +**The site follows the newest tag.** The website deploys from the newest `vN.N.N` release tag +(rule 7), wherever it was cut. A patch tag on a maintenance branch therefore becomes what +metaobjects.dev shows, including its payload and coordinates, until the next release is tagged. +The converse is enforced: `finish-release` refuses to tag a patch on a line older than a tag +that already exists (`v1.2.3` once `v1.3.0` exists), because the deploy would never resolve it. +So a maintenance patch is for a line that is still the newest release. The same holds on npm: +`release.mjs` publishes to `latest`, and a patch cut after a newer minor shipped would move +`latest` backwards. + +**Then bring the fix to `main`.** A maintenance branch is never merged back wholesale (its +version bumps and CHANGELOG would collide with `main`'s). Cherry-pick or re-land each fix on +`main` by PR. + ## Isolated patch (one package) If only one package changed (e.g. a `cli` bugfix), bump just that package, `rm bun.lock && bun diff --git a/scripts/ci-local.sh b/scripts/ci-local.sh index 11b50b23e..4e3a92a4c 100755 --- a/scripts/ci-local.sh +++ b/scripts/ci-local.sh @@ -487,7 +487,7 @@ gate_site_reference() { bun_install && bun scripts/build-site-reference.ts --che # exercised) are the ones worth a test at all. See scripts/maven-coordinate.mjs. # And the publish workflows' tag check (scripts/check-release-tag.mjs), whose test also reads # each real manifest, so a layout change fails here rather than on a release tag. -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; } +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; } # ── repo-root scripts/ typechecks ───────────────────────────────────────────── # `bun test` transpiles per file and never typechecks, and `bun run --filter '*' diff --git a/scripts/eject-release-gate.test.ts b/scripts/eject-release-gate.test.ts index 98e743f50..90f45b093 100644 --- a/scripts/eject-release-gate.test.ts +++ b/scripts/eject-release-gate.test.ts @@ -102,9 +102,9 @@ describe("eject release gate — the command and its wiring", () => { // ADR-0034 Amendment 8 makes the gate the first preflight check of `release.mjs`. The // check after it is the branch check, so a fixture on another branch tells the two apart: - // a refused version stops before "must be on main", and an allowed one reaches it. + // a refused version stops before "not on main", and an allowed one reaches it. test("release.mjs asks the gate first in its preflight, and stops on a refusal", () => { - const RELEASE_SCRIPTS = ["release.mjs", "lib/changelog-promote.mjs", "publish-set.mjs", "maven-coordinate.mjs"]; + const RELEASE_SCRIPTS = ["release.mjs", "lib/changelog-promote.mjs", "lib/release-branch.mjs", "publish-set.mjs", "maven-coordinate.mjs"]; const onBranch = (pending: (typeof ENTRY)[]) => { const root = repoWith(JSON.stringify(manifest(pending)), RELEASE_SCRIPTS); const git = (...args: string[]) => spawnSync("git", ["-C", root, ...args], { encoding: "utf8" }); @@ -119,11 +119,11 @@ describe("eject release gate — the command and its wiring", () => { const refused = release(blocked, "1.1.0"); expect(refused.code).not.toBe(0); expect(refused.out).toContain("the eject contract does not hold yet"); - expect(refused.out).not.toContain("must be on main"); + expect(refused.out).not.toContain("not on main"); for (const allowed of [release(blocked, "1.1.0-rc.1"), release(onBranch([]), "1.1.0")]) { expect(allowed.out).not.toContain("the eject contract does not hold yet"); - expect(allowed.out).toContain("must be on main (you are on not-main)"); + expect(allowed.out).toContain("not on main or a release/. maintenance branch (you are on not-main)"); } }); diff --git a/scripts/finish-release.mjs b/scripts/finish-release.mjs index b3c790952..f847d8d1e 100644 --- a/scripts/finish-release.mjs +++ b/scripts/finish-release.mjs @@ -37,6 +37,7 @@ import { dirname, join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import { mavenVersion } from "./maven-coordinate.mjs"; import { ejectReleaseRefusalAt } from "./eject-release-gate.mjs"; +import { releaseBranchRefusal } from "./lib/release-branch.mjs"; const REPO = resolve(dirname(fileURLToPath(import.meta.url)), ".."); const CHECK_ONLY = process.argv.includes("--check"); @@ -80,8 +81,13 @@ ok("eject contract: the pending list is empty"); if (out("git status --porcelain") !== "") { die("working tree is dirty — commit or stash before tagging, or the tag names a tree you did not review"); } -if (out("git rev-parse --abbrev-ref HEAD") !== "main") die("not on main"); -// NOT `|| true`. A swallowed fetch leaves `origin/main` at a STALE remote-tracking ref, +// `main`, or a `release/.` maintenance branch tagging a version on its own +// line (scripts/lib/release-branch.mjs). The sync check below compares against THAT +// branch's remote, never origin/main. +const branch = out("git rev-parse --abbrev-ref HEAD"); +const branchRefusal = releaseBranchRefusal(branch, VERSION); +if (branchRefusal !== null) die(branchRefusal); +// NOT `|| true`. A swallowed fetch leaves `origin/` at a STALE remote-tracking ref, // and the very next comparison then prints "synced with origin" having verified nothing — // with git's own "Could not read from remote repository" scrolling past just above the // tick. The realistic case is the port-bump commit pushed from another checkout while @@ -93,10 +99,12 @@ try { die(`git fetch origin failed, so "synced with origin" cannot be verified: ` + `${e instanceof Error ? e.message : String(e)}`); } -if (out("git rev-parse HEAD") !== out("git rev-parse origin/main")) { - die("HEAD is not origin/main — push first; the deploy clones the REMOTE tag"); +// `|| true` here is not the swallow warned about above: a maintenance branch that was +// never pushed has no `origin/`, and that must read as "not synced", not crash. +if (out("git rev-parse HEAD") !== out(`git rev-parse --verify --quiet origin/${branch} || true`)) { + die(`HEAD is not origin/${branch} — push first; the deploy clones the REMOTE tag`); } -ok("on main, clean, synced with origin"); +ok(`on ${branch}, clean, synced with origin`); // ── 2. the tag is free ─────────────────────────────────────────────────────── // Never move a tag. A moved tag silently changes what the website deploys, and any diff --git a/scripts/finish-release.test.ts b/scripts/finish-release.test.ts index ea089fc87..713bdfe6e 100644 --- a/scripts/finish-release.test.ts +++ b/scripts/finish-release.test.ts @@ -36,6 +36,8 @@ const SCRIPT = readFileSync(resolve(REPO, "scripts/finish-release.mjs"), "utf8") const MAVEN_COORD = readFileSync(resolve(REPO, "scripts/maven-coordinate.mjs"), "utf8"); // Gate 0 asks the eject release gate, and the fixture ships the real one for the same reason. const EJECT_GATE = readFileSync(resolve(REPO, "scripts/eject-release-gate.mjs"), "utf8"); +// Gate 1's branch rule, shared with release.mjs — the real module, for the same reason. +const RELEASE_BRANCH = readFileSync(resolve(REPO, "scripts/lib/release-branch.mjs"), "utf8"); const EJECT_MANIFEST = "fixtures/generator-registry-conformance/registry.json"; /** The shared file as the release branch leaves it: nothing pending. */ const EJECT_CLEAR = `${JSON.stringify({ eject: { pending: [] } })}\n`; @@ -173,6 +175,7 @@ function makeRepo(spec: Spec = {}): Fixture { "scripts/finish-release.mjs": SCRIPT, "scripts/maven-coordinate.mjs": MAVEN_COORD, "scripts/eject-release-gate.mjs": EJECT_GATE, + "scripts/lib/release-branch.mjs": RELEASE_BRANCH, })) { const full = join(work, rel); mkdirSync(dirname(full), { recursive: true }); @@ -291,6 +294,46 @@ describe("finish-release gate 1: the tree that will be tagged", () => { expect(r.out).toContain("HEAD is not origin/main"); }); + // A maintenance branch `release/.` may tag a patch on its own line; the + // rule itself is unit-tested in scripts/test-release-branch.mjs. These cases prove the + // script wires it: the branch is accepted, a version off its line is refused, and the + // sync check compares against origin/, never origin/main. + const onMaintenance = (name: string, push = true) => { + const f = makeRepo(); + f.git(f.work, "checkout", "--quiet", "-b", name); + if (push) f.git(f.work, "push", "--quiet", "-u", "origin", name); + return f; + }; + + test("a maintenance branch on the release's own line passes gate 1", () => { + const r = onMaintenance("release/0.24").run(RELEASE, "--check"); + expect(r.out).toContain("on release/0.24, clean, synced with origin"); + expect(r.code).toBe(0); + }); + + test("a maintenance branch refuses a version off its line", () => { + const r = onMaintenance("release/0.23").run(RELEASE, "--check"); + expect(r.code).not.toBe(0); + expect(r.out).toContain("cuts only 0.23.x"); + expect(r.out).not.toContain("synced with origin"); + }); + + test("a maintenance branch syncs against its OWN remote, not origin/main", () => { + const f = onMaintenance("release/0.24"); + writeFileSync(join(f.work, "NOTES.md"), "unpushed\n"); + f.git(f.work, "add", "-A"); + f.git(f.work, "commit", "--quiet", "-m", "local only"); + const r = f.run(RELEASE, "--check"); + expect(r.code).not.toBe(0); + expect(r.out).toContain("HEAD is not origin/release/0.24"); + }); + + test("a maintenance branch never pushed is refused, not crashed on", () => { + const r = onMaintenance("release/0.24", false).run(RELEASE, "--check"); + expect(r.code).not.toBe(0); + expect(r.out).toContain("HEAD is not origin/release/0.24"); + }); + // The defect: the fetch was `|| true`, so a failure left `origin/main` at a stale // remote-tracking ref and the very next line printed "synced with origin" having // 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", () => { expect(f.git(f.origin, "tag", "-l")).toContain(`v${RELEASE}`); }); + test("tags and pushes from a maintenance branch, leaving origin/main where it was", () => { + const f = makeRepo(); + const mainBefore = f.git(f.origin, "rev-parse", "main"); + f.git(f.work, "checkout", "--quiet", "-b", "release/0.24"); + writeFileSync(join(f.work, "NOTES.md"), "the patch\n"); + f.git(f.work, "add", "-A"); + f.git(f.work, "commit", "--quiet", "-m", "patch on the maintenance line"); + f.git(f.work, "push", "--quiet", "-u", "origin", "release/0.24"); + const r = f.run(RELEASE); + expect(r.out).toContain(`cut and pushed v${RELEASE}`); + expect(r.code).toBe(0); + expect(f.git(f.origin, "rev-parse", `v${RELEASE}^{commit}`)).toBe(f.git(f.work, "rev-parse", "HEAD")); + expect(f.git(f.origin, "rev-parse", "main")).toBe(mainBefore); + }); + test("--check cuts nothing", () => { const f = makeRepo(); expect(f.run(RELEASE, "--check").code).toBe(0); diff --git a/scripts/lib/release-branch.mjs b/scripts/lib/release-branch.mjs new file mode 100644 index 000000000..99cce83bd --- /dev/null +++ b/scripts/lib/release-branch.mjs @@ -0,0 +1,38 @@ +// Which branch a release may be cut from — shared by `scripts/release.mjs` and +// `scripts/finish-release.mjs`, so the two cannot disagree about it. +// +// Two kinds of branch qualify: +// +// - `main`, for every release, as before. +// - a maintenance branch named `release/.`, for a PATCH on a line `main` +// has moved past. It may cut only versions on its own line: `release/1.2` cuts 1.2.x +// and nothing else, because a 1.3.0 cut from it would ship a minor without the work +// `main` holds for that minor. +// +// The caller pushes to, and compares HEAD against, `origin/` — never `origin/main` +// when it is on a maintenance branch. + +/** The pattern a maintenance branch name must match. */ +export const MAINTENANCE_BRANCH = /^release\/(\d+)\.(\d+)$/; + +/** + * Why `version` may not be released from `branch`, or `null` when it may. + * + * @param {string} branch the current branch, as `git rev-parse --abbrev-ref HEAD` prints it + * @param {string} version the version being cut (`1.2.2`, or `1.2.2-rc.1` for release.mjs) + * @returns {string | null} + */ +export function releaseBranchRefusal(branch, version) { + if (branch === "main") return null; + const m = MAINTENANCE_BRANCH.exec(branch); + if (m === null) { + return `not on main or a release/. maintenance branch (you are on ${branch})`; + } + const [, major, minor] = m; + const v = /^(\d+)\.(\d+)\./.exec(version); + if (v === null || v[1] !== major || v[2] !== minor) { + return `${branch} is the ${major}.${minor} maintenance branch and cuts only ${major}.${minor}.x — ` + + `${version} is not on that line (cut it from main, or from its own release/.)`; + } + return null; +} diff --git a/scripts/release.mjs b/scripts/release.mjs index 04ef11d35..f327b2652 100644 --- a/scripts/release.mjs +++ b/scripts/release.mjs @@ -33,6 +33,7 @@ import { createInterface } from "node:readline/promises"; import { publishSet } from "./publish-set.mjs"; import { mavenVersion } from "./maven-coordinate.mjs"; import { ejectReleaseRefusalAt } from "./eject-release-gate.mjs"; +import { releaseBranchRefusal } from "./lib/release-branch.mjs"; const VERSION = process.argv[2]; const DRY = process.argv.includes("--dry-run"); @@ -70,10 +71,14 @@ console.log(`\n── Releasing ${VERSION}${DRY ? " (DRY RUN)" : ""} ──\n`) const ejectRefusal = ejectReleaseRefusalAt(VERSION, join(dirname(fileURLToPath(import.meta.url)), "..")); if (ejectRefusal !== null) die(ejectRefusal); +// `main`, or a `release/.` maintenance branch cutting a version on its own +// line (scripts/lib/release-branch.mjs). Everything below that pushes or compares against +// the remote uses THIS branch, so a maintenance cut never touches main. const branch = out("git rev-parse --abbrev-ref HEAD"); -if (branch !== "main") die(`must be on main (you are on ${branch})`); +const branchRefusal = releaseBranchRefusal(branch, VERSION); +if (branchRefusal !== null) die(branchRefusal); sh("git fetch origin", { quiet: true }); -if (out("git rev-list --count HEAD..origin/main") !== "0") die("main is behind origin/main — pull first"); +if (out(`git rev-list --count HEAD..origin/${branch}`) !== "0") die(`${branch} is behind origin/${branch} — pull first`); // Clean tree, except the CHANGELOG (we promote its [Unreleased] section) and untracked noise. const dirty = out("git status --porcelain").split("\n") @@ -129,7 +134,7 @@ const taken = (await Promise.all(set.map(async (p) => { if (taken.length) die(`${VERSION} is already published for:\n ${taken.join("\n ")}\n` + `npm versions are permanent — pick the next free version.`); -ok(`preflight: on main, synced, ${VERSION} free on all ${set.length} packages`); +ok(`preflight: on ${branch}, synced, ${VERSION} free on all ${set.length} packages`); ok(`lockstep set @ ${current}: ${set.length} packages → ${VERSION}`); // The showcase corpus is what metaobjects.dev publishes as "real `meta gen` output", @@ -262,7 +267,7 @@ for (const pkg of ordered) { // --- PHASE 8: push (the tag is NOT cut here) ------------------------------- // This script publishes npm, which is one of FOUR registries. The PyPI/NuGet/Maven -// version bump is a separate, later commit — so at this point `main` states the new npm +// version bump is a separate, later commit — so at this point the branch states the new npm // coordinate and three stale ones, and the site payload committed above says exactly // that. // @@ -274,8 +279,8 @@ for (const pkg of ordered) { // // So the tag moves to the END of the coordinated cut: `scripts/finish-release.mjs`, // which refuses to tag until the payload's coordinates match what actually shipped. -sh("git push origin main", { quiet: true }); -ok("pushed main (tag deferred to finish-release)"); +sh(`git push origin ${branch}`, { quiet: true }); +ok(`pushed ${branch} (tag deferred to finish-release)`); // --- PHASE 11: post-publish smoke (the RC's safety net) ------------------- // 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 console.log(` The website pins to v${VERSION}, so tagging before step 1 publishes three stale versions.`); console.log(` Docs version refs are NOT auto-bumped (low-value churn for a patch); batch them when convenient.`); console.log(` The site payload IS auto-bumped and committed here — but only its npm coordinate.`); -console.log(` The PyPI/NuGet/Maven bump commit must run \`bun run site:payload\` or gates goes red on main.\n`); +console.log(` The PyPI/NuGet/Maven bump commit must run \`bun run site:payload\` or gates goes red on ${branch}.\n`); diff --git a/scripts/test-release-branch.mjs b/scripts/test-release-branch.mjs new file mode 100644 index 000000000..623c8113b --- /dev/null +++ b/scripts/test-release-branch.mjs @@ -0,0 +1,42 @@ +#!/usr/bin/env node +// Tests for scripts/lib/release-branch.mjs — which branch a release may be cut from. +// +// node scripts/test-release-branch.mjs + +import { releaseBranchRefusal } from "./lib/release-branch.mjs"; + +let fails = 0; +const check = (cond, label) => (cond ? console.log(`ok: ${label}`) : (console.error(`FAIL: ${label}`), fails++)); +const refused = (branch, version) => releaseBranchRefusal(branch, version) !== null; + +// main is unchanged: any version, any line. +check(!refused("main", "1.2.2"), "main cuts a patch"); +check(!refused("main", "1.3.0"), "main cuts a minor"); +check(!refused("main", "2.0.0-rc.1"), "main cuts a release candidate"); + +// A maintenance branch cuts its own line only. +check(!refused("release/1.2", "1.2.2"), "release/1.2 cuts 1.2.2"); +check(!refused("release/1.2", "1.2.10"), "release/1.2 cuts 1.2.10"); +check(!refused("release/1.2", "1.2.3-rc.1"), "release/1.2 cuts a 1.2.x release candidate"); +check(refused("release/1.2", "1.3.0"), "release/1.2 refuses 1.3.0 (mismatched minor)"); +check(refused("release/1.2", "1.1.9"), "release/1.2 refuses 1.1.9 (an older minor)"); +check(refused("release/1.2", "2.2.0"), "release/1.2 refuses 2.2.0 (mismatched major)"); +check(refused("release/1.2", "1.20.0"), "release/1.2 refuses 1.20.0 (a prefix is not a match)"); +check(refused("release/1.20", "1.2.0"), "release/1.20 refuses 1.2.0"); +check(releaseBranchRefusal("release/1.2", "1.3.0")?.includes("cuts only 1.2.x") === true, + "the mismatch refusal names the line the branch cuts"); + +// Anything else is refused, as before. +check(refused("release-prep", "1.2.2"), "an ordinary branch is refused"); +check(refused("release/1", "1.2.2"), "release/ alone is not a maintenance branch"); +check(refused("release/1.2.x", "1.2.2"), "release/1.2.x is not a maintenance branch"); +check(refused("fix/release/1.2", "1.2.2"), "a nested name is not a maintenance branch"); +check(refused("HEAD", "1.2.2"), "a detached HEAD is refused"); +check(releaseBranchRefusal("release-prep", "1.2.2")?.includes("not on main") === true, + "the refusal for an ordinary branch still says it is not on main"); + +if (fails > 0) { + console.error(`\n${fails} check(s) failed`); + process.exit(1); +} +console.log("\nall checks passed"); diff --git a/tsconfig.scripts.json b/tsconfig.scripts.json index 1d8f364c5..bde36e2df 100644 --- a/tsconfig.scripts.json +++ b/tsconfig.scripts.json @@ -149,6 +149,7 @@ "scripts/maven-coordinate.mjs", "scripts/eject-release-gate.mjs", "scripts/lib/changelog-promote.mjs", + "scripts/lib/release-branch.mjs", "scripts/check-release-tag.mjs" ] } From d290bd4ec429eaa75022044c8a763138800bce09 Mon Sep 17 00:00:00 2001 From: Doug Mealing Date: Fri, 13 Nov 2026 18:54:10 -0500 Subject: [PATCH 3/5] no-mistakes(review): gate latest-regression before npm publish; clean unpushed-branch die --- docs/RELEASING.md | 4 ++- scripts/finish-release.mjs | 12 +++------ scripts/lib/release-branch.mjs | 43 +++++++++++++++++++++++++++++++++ scripts/release.mjs | 12 ++++++++- scripts/test-release-branch.mjs | 31 +++++++++++++++++++++++- 5 files changed, 91 insertions(+), 11 deletions(-) diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 857d4e326..0793a8f25 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -642,7 +642,9 @@ The converse is enforced: `finish-release` refuses to tag a patch on a line olde that already exists (`v1.2.3` once `v1.3.0` exists), because the deploy would never resolve it. So a maintenance patch is for a line that is still the newest release. The same holds on npm: `release.mjs` publishes to `latest`, and a patch cut after a newer minor shipped would move -`latest` backwards. +`latest` backwards — so `release.mjs` refuses, in its preflight and before anything is +published, any version older than the newest release tag (resolved the same way the site +deploy resolves its tag). It offers no non-`latest` dist-tag path. **Then bring the fix to `main`.** A maintenance branch is never merged back wholesale (its version bumps and CHANGELOG would collide with `main`'s). Cherry-pick or re-land each fix on diff --git a/scripts/finish-release.mjs b/scripts/finish-release.mjs index f847d8d1e..5fb4529d3 100644 --- a/scripts/finish-release.mjs +++ b/scripts/finish-release.mjs @@ -37,7 +37,7 @@ import { dirname, join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import { mavenVersion } from "./maven-coordinate.mjs"; import { ejectReleaseRefusalAt } from "./eject-release-gate.mjs"; -import { releaseBranchRefusal } from "./lib/release-branch.mjs"; +import { releaseBranchRefusal, newestNpmReleaseTag } from "./lib/release-branch.mjs"; const REPO = resolve(dirname(fileURLToPath(import.meta.url)), ".."); const CHECK_ONLY = process.argv.includes("--check"); @@ -386,13 +386,9 @@ ok("the llms mirrors state this release"); // newest tag of a frozen line and passes green forever. After the 1.0 cut it would have // resolved v0.25.0 at every future release, so the check could never fire again — the same // defect that kept the live site on 0.25.0 with every deploy step green. Nothing here needs -// maintaining at the next major. -const resolved = out(`git tag -l 'v*' | grep -E '^v[0-9]+\\.[0-9]+\\.[0-9]+$' | sort -rV || true`) - .split("\n").map((t) => t.trim()).filter(Boolean) - .find((t) => { - const pkg = out(`git show ${t}:server/typescript/packages/cli/package.json 2>/dev/null || true`); - try { return JSON.parse(pkg).version === t.slice(1); } catch { return false; } - }) ?? ""; +// maintaining at the next major. The selector itself is shared with `release.mjs` +// (scripts/lib/release-branch.mjs), so the two cannot disagree about the npm line. +const resolved = newestNpmReleaseTag(out); const wouldResolve = [resolved, tag].filter(Boolean).sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).at(-1); if (wouldResolve !== tag) { diff --git a/scripts/lib/release-branch.mjs b/scripts/lib/release-branch.mjs index 99cce83bd..51be2a2a8 100644 --- a/scripts/lib/release-branch.mjs +++ b/scripts/lib/release-branch.mjs @@ -36,3 +36,46 @@ export function releaseBranchRefusal(branch, version) { } return null; } + +/** + * The newest tag on the npm release line, the way the site deploy resolves it: the newest + * `vN.N.N` whose `server/typescript/packages/cli/package.json` is versioned as the tag — + * the property that DEFINES the npm line, never a version prefix (the JVM `v7.20.12` ships + * cli `0.20.11` and must not count). `""` when no release tag exists. + * + * @param {(cmd: string) => string} out run a command and return its trimmed stdout, like + * each script's own `out` + * @returns {string} + */ +export function newestNpmReleaseTag(out) { + return out(`git tag -l 'v*' | grep -E '^v[0-9]+\\.[0-9]+\\.[0-9]+$' | sort -rV || true`) + .split("\n").map((t) => t.trim()).filter(Boolean) + .find((t) => { + const pkg = out(`git show ${t}:server/typescript/packages/cli/package.json 2>/dev/null || true`); + try { return JSON.parse(pkg).version === t.slice(1); } catch { return false; } + }) ?? ""; +} + +/** + * Why `version` may not be released while `newestTag` is the newest release tag, or `null` + * when it may. `bun publish` tags `latest`, so a version older than the newest release + * would move `latest` backwards — including an `-rc` cut on a line a newer release passed. + * + * @param {string} version the version being cut (`1.2.4`, or `1.2.4-rc.1`) + * @param {string} newestTag the newest npm-line release tag (`v1.3.0`), or `""` if none + * @returns {string | null} + */ +export function latestRegressionRefusal(version, newestTag) { + if (newestTag === "") return null; + const a = /^(\d+)\.(\d+)\.(\d+)/.exec(version); + const b = /^v(\d+)\.(\d+)\.(\d+)$/.exec(newestTag); + if (a === null || b === null) return null; + for (let i = 1; i <= 3; i++) { + if (Number(a[i]) === Number(b[i])) continue; + if (Number(a[i]) > Number(b[i])) return null; + return `${version} is older than ${newestTag.slice(1)}, the newest release — npm publishes to ` + + `\`latest\`, so this would move \`latest\` backwards. A patch on a line a newer release ` + + `has passed needs a non-\`latest\` dist-tag path this script does not yet offer.`; + } + return null; +} diff --git a/scripts/release.mjs b/scripts/release.mjs index f327b2652..31a985fbd 100644 --- a/scripts/release.mjs +++ b/scripts/release.mjs @@ -33,7 +33,7 @@ import { createInterface } from "node:readline/promises"; import { publishSet } from "./publish-set.mjs"; import { mavenVersion } from "./maven-coordinate.mjs"; import { ejectReleaseRefusalAt } from "./eject-release-gate.mjs"; -import { releaseBranchRefusal } from "./lib/release-branch.mjs"; +import { releaseBranchRefusal, newestNpmReleaseTag, latestRegressionRefusal } from "./lib/release-branch.mjs"; const VERSION = process.argv[2]; const DRY = process.argv.includes("--dry-run"); @@ -78,6 +78,9 @@ const branch = out("git rev-parse --abbrev-ref HEAD"); const branchRefusal = releaseBranchRefusal(branch, VERSION); if (branchRefusal !== null) die(branchRefusal); sh("git fetch origin", { quiet: true }); +if (out(`git rev-parse --verify --quiet origin/${branch} || true`) === "") { + die(`${branch} has no origin/${branch} — push the branch first`); +} if (out(`git rev-list --count HEAD..origin/${branch}`) !== "0") die(`${branch} is behind origin/${branch} — pull first`); // Clean tree, except the CHANGELOG (we promote its [Unreleased] section) and untracked noise. @@ -87,6 +90,13 @@ if (dirty.length) die(`uncommitted changes:\n${dirty.join("\n")}\n(commit or sta if (out(`git tag -l v${VERSION}`)) die(`tag v${VERSION} already exists`); +// `bun publish` tags `latest`, so a version older than the newest release would move +// `latest` backwards — finish-release gate 6 catches that only after the publish; this +// refuses it before anything irreversible. Same npm-line tag resolution the site deploy +// uses (scripts/lib/release-branch.mjs). +const latestRefusal = latestRegressionRefusal(VERSION, newestNpmReleaseTag(out)); +if (latestRefusal !== null) die(latestRefusal); + // Can we publish AT ALL? Checked here, before the version bump, because the bump is // committed and pushed long before the first `bun publish` — so discovering a dead // credential at the publish step strands the release mid-flight. The 0.24.0 cut found diff --git a/scripts/test-release-branch.mjs b/scripts/test-release-branch.mjs index 623c8113b..a0f64d51c 100644 --- a/scripts/test-release-branch.mjs +++ b/scripts/test-release-branch.mjs @@ -3,7 +3,7 @@ // // node scripts/test-release-branch.mjs -import { releaseBranchRefusal } from "./lib/release-branch.mjs"; +import { releaseBranchRefusal, latestRegressionRefusal, newestNpmReleaseTag } from "./lib/release-branch.mjs"; let fails = 0; const check = (cond, label) => (cond ? console.log(`ok: ${label}`) : (console.error(`FAIL: ${label}`), fails++)); @@ -35,6 +35,35 @@ check(refused("HEAD", "1.2.2"), "a detached HEAD is refused"); check(releaseBranchRefusal("release-prep", "1.2.2")?.includes("not on main") === true, "the refusal for an ordinary branch still says it is not on main"); +// `latest` never moves backwards: `bun publish` tags `latest`, so a version older than the +// newest release must be refused. The oracle is npm's own dist-tag semantics: `latest` +// resolves to whichever version was published last, so publishing an older one regresses it. +check(latestRegressionRefusal("1.2.4", "v1.3.0") !== null, + "a version older than the newest release is refused"); +check(latestRegressionRefusal("1.2.4-rc.1", "v1.3.0") !== null, + "an RC on a line a newer release passed is refused too"); +check(latestRegressionRefusal("1.3.1", "v1.3.0") === null, + "a version newer than the newest release passes"); +check(latestRegressionRefusal("1.2.4", "v1.2.3") === null, + "a patch on the newest release line passes"); +check(latestRegressionRefusal("1.2.4", "") === null, + "no released tag yet passes"); +check(latestRegressionRefusal("1.2.4", "v1.3.0")?.includes("`latest` backwards") === true, + "the refusal names the `latest` constraint"); + +// The newest release is resolved by the property that defines the npm line (deploy.yml's +// selector): the newest `vN.N.N` whose cli/package.json is versioned as the tag. A version +// prefix would wrongly pick `v8.2.2` (no cli tree) or the JVM `v7.20.12` (cli 0.20.11). +const cliOf = new Map([["v1.3.0", "1.3.0"], ["v1.2.2", "1.2.2"], ["v7.20.12", "0.20.11"]]); +const fakeOut = (cmd) => { + if (cmd.startsWith("git tag -l")) return "v8.2.2\nv1.3.0\nv1.2.2\nv7.20.12"; + const t = /^git show (v[\d.]+):/.exec(cmd)?.[1]; + const v = t === undefined ? undefined : cliOf.get(t); + return v === undefined ? "" : `{"name":"@metaobjectsdev/cli","version":"${v}"}`; +}; +check(newestNpmReleaseTag(fakeOut) === "v1.3.0", + "the newest npm-line tag wins; a treeless tag and the JVM line are skipped"); + if (fails > 0) { console.error(`\n${fails} check(s) failed`); process.exit(1); From b829e495da15ad677f5744406bc27e412590f706 Mon Sep 17 00:00:00 2001 From: Doug Mealing Date: Fri, 13 Nov 2026 18:58:17 -0500 Subject: [PATCH 4/5] no-mistakes(review): refuse an rc of an already-shipped version --- docs/RELEASING.md | 5 +++-- scripts/lib/release-branch.mjs | 10 ++++++++-- scripts/test-release-branch.mjs | 6 ++++++ 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 0793a8f25..382273732 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -643,8 +643,9 @@ that already exists (`v1.2.3` once `v1.3.0` exists), because the deploy would ne So a maintenance patch is for a line that is still the newest release. The same holds on npm: `release.mjs` publishes to `latest`, and a patch cut after a newer minor shipped would move `latest` backwards — so `release.mjs` refuses, in its preflight and before anything is -published, any version older than the newest release tag (resolved the same way the site -deploy resolves its tag). It offers no non-`latest` dist-tag path. +published, any version older than the newest release tag, and any release candidate of a +version that has already shipped (npm sorts it below the full release; resolved the same +way the site deploy resolves its tag). It offers no non-`latest` dist-tag path. **Then bring the fix to `main`.** A maintenance branch is never merged back wholesale (its version bumps and CHANGELOG would collide with `main`'s). Cherry-pick or re-land each fix on diff --git a/scripts/lib/release-branch.mjs b/scripts/lib/release-branch.mjs index 51be2a2a8..50b181321 100644 --- a/scripts/lib/release-branch.mjs +++ b/scripts/lib/release-branch.mjs @@ -59,7 +59,9 @@ export function newestNpmReleaseTag(out) { /** * Why `version` may not be released while `newestTag` is the newest release tag, or `null` * when it may. `bun publish` tags `latest`, so a version older than the newest release - * would move `latest` backwards — including an `-rc` cut on a line a newer release passed. + * would move `latest` backwards — including an `-rc` cut on a line a newer release passed, + * and an `-rc` of the very version that already shipped (npm sorts `1.2.4-rc.1` below + * `1.2.4`). * * @param {string} version the version being cut (`1.2.4`, or `1.2.4-rc.1`) * @param {string} newestTag the newest npm-line release tag (`v1.3.0`), or `""` if none @@ -77,5 +79,9 @@ export function latestRegressionRefusal(version, newestTag) { `\`latest\`, so this would move \`latest\` backwards. A patch on a line a newer release ` + `has passed needs a non-\`latest\` dist-tag path this script does not yet offer.`; } - return null; + return /-rc\.\d+$/.test(version) + ? `${version} is a release candidate for ${newestTag.slice(1)}, which has already shipped — ` + + `npm sorts it below the full release, so publishing to \`latest\` would move \`latest\` ` + + `backwards.` + : null; } diff --git a/scripts/test-release-branch.mjs b/scripts/test-release-branch.mjs index a0f64d51c..d3e67e0ec 100644 --- a/scripts/test-release-branch.mjs +++ b/scripts/test-release-branch.mjs @@ -42,6 +42,12 @@ check(latestRegressionRefusal("1.2.4", "v1.3.0") !== null, "a version older than the newest release is refused"); check(latestRegressionRefusal("1.2.4-rc.1", "v1.3.0") !== null, "an RC on a line a newer release passed is refused too"); +check(latestRegressionRefusal("1.2.4-rc.1", "v1.2.4") !== null, + "an RC of the version that already shipped is refused"); +check(latestRegressionRefusal("1.2.4", "v1.2.4") === null, + "the released version itself is not a regression"); +check(latestRegressionRefusal("1.3.0-rc.1", "v1.2.4") === null, + "an RC of a NEWER triple passes"); check(latestRegressionRefusal("1.3.1", "v1.3.0") === null, "a version newer than the newest release passes"); check(latestRegressionRefusal("1.2.4", "v1.2.3") === null, From 4e5b4cd1efc465f3150fe86ad1a1525466e12f13 Mon Sep 17 00:00:00 2001 From: Doug Mealing Date: Fri, 13 Nov 2026 21:23:05 -0500 Subject: [PATCH 5/5] no-mistakes(document): docs: fix RELEASING.md main-only release claims --- docs/RELEASING.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 382273732..05b2cbbdc 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -186,7 +186,9 @@ Publish in tier order so a dependent never lands before its dependency. **`forge released. `v0.24.5` carries exactly that, and nothing caught it because no page displayed a coordinate yet. - So `release.mjs` pushes `main` and **stops**. After the ports are bumped, committed, + So `release.mjs` pushes the branch it runs on (`main`, or a `release/.` + maintenance branch — see the maintenance-branch section below) and **stops**. After the + ports are bumped, committed, pushed and tagged (`python-v*`, `csharp-v*`, `java-v.*` — `java-v8.*` at the 1.0 cut, NOT `java-v7.*`), run: @@ -733,7 +735,9 @@ lock the repo/owner IDs against resurrection attacks.) ## Procedure -1. **Pick the publish commit on `main`** (a stable, merged tip — not a mid-refactor branch). Ensure +1. **Pick the publish commit on the branch the release is cut from** (`main`, or the + `release/.` maintenance branch for a patch — the workflow publishes the + COMMITTED ``, so the tag must name that branch's tree). Ensure the packaging config + `publish-csharp.yml` are on it. Set `` in `Directory.Build.props`. 2. **Validate locally** (catches immutable-version mistakes before they're permanent): ```bash