Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
45 changes: 43 additions & 2 deletions docs/RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<major>.<minor>`
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<npm major + 7>.*` — `java-v8.*` at the
1.0 cut, NOT `java-v7.*`), run:

Expand Down Expand Up @@ -614,6 +616,43 @@ default, so a dispatch meant to report cannot write.
Then verify: `npm dist-tag ls @metaobjectsdev/<pkg>` — authoritative, where `npm view` is
CDN-cached and lags right after publish.

## Patch from a maintenance branch (`release/<major>.<minor>`)

**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/<major>.<minor>` (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/<major>.<minor>` 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 — so `release.mjs` refuses, in its preflight and before anything is
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
`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
Expand Down Expand Up @@ -696,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/<major>.<minor>` maintenance branch for a patch — the workflow publishes the
COMMITTED `<Version>`, so the tag must name that branch's tree). Ensure
the packaging config + `publish-csharp.yml` are on it. Set `<Version>` in `Directory.Build.props`.
2. **Validate locally** (catches immutable-version mistakes before they're permanent):
```bash
Expand Down
2 changes: 1 addition & 1 deletion scripts/ci-local.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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 '*'
Expand Down
8 changes: 4 additions & 4 deletions scripts/eject-release-gate.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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" });
Expand All @@ -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/<major>.<minor> maintenance branch (you are on not-main)");
}
});

Expand Down
28 changes: 16 additions & 12 deletions scripts/finish-release.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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, newestNpmReleaseTag } from "./lib/release-branch.mjs";

const REPO = resolve(dirname(fileURLToPath(import.meta.url)), "..");
const CHECK_ONLY = process.argv.includes("--check");
Expand Down Expand Up @@ -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/<major>.<minor>` 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/<branch>` 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
Expand All @@ -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/<branch>`, 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
Expand Down Expand Up @@ -378,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) {
Expand Down
58 changes: 58 additions & 0 deletions scripts/finish-release.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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`;
Expand Down Expand Up @@ -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 });
Expand Down Expand Up @@ -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/<major>.<minor>` 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/<that branch>, 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
Expand Down Expand Up @@ -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);
Expand Down
Loading
Loading