diff --git a/.changeset/pre.json b/.changeset/pre.json index 9a89b8a..f679993 100644 --- a/.changeset/pre.json +++ b/.changeset/pre.json @@ -1,4 +1,4 @@ { "mode": "pre", - "tag": "alpha" + "tag": "beta" } diff --git a/RELEASING.md b/RELEASING.md index 99c137e..94cc456 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -22,7 +22,7 @@ When a release makes sense (Afzal or the team lead decides): ```sh git switch -c release- origin/main -npm run version-packages # changeset version + version constant + lockfile sync +npm run version-packages # changeset version + prerelease counter + version constant + lockfile sync git diff # review the version bump and CHANGELOG.md ``` @@ -32,7 +32,7 @@ git diff # review the version bump and CHANGELOG.md - writes `packages/react-data-export/CHANGELOG.md`, - updates the playground's dependency on the package. -It then runs `scripts/sync-version.mjs`, which sets the `version` constant in `packages/react-data-export/src/index.ts` to the new version (`changeset version` never edits source files). It fails if it can't find exactly one such constant, so renaming the constant can't silently break the sync. +It then runs `scripts/reset-pre-counter.mjs`, which restarts the prerelease number at 0 when the prerelease tag changed (see [§3](#3-prereleases-pre-mode)), and `scripts/sync-version.mjs`, which sets the `version` constant in `packages/react-data-export/src/index.ts` to the new version (`changeset version` never edits source files). It fails if it can't find exactly one such constant, so renaming the constant can't silently break the sync. Finally it runs `npm install --package-lock-only`. Without that step, `package-lock.json` would still list the old version, and `npm ci` (in CI and in the release job) would fail. @@ -40,16 +40,49 @@ Open the pull request. Its **Release dry run** CI job shows what merging would d ## 3. Prereleases (pre mode) -1.0 starts out as prereleases on the `next` dist-tag, so `npm install react-data-export` keeps getting 0.6.0 (`latest`) until 1.0.0 is final. +1.0 ships as prereleases on the `next` dist-tag, so `npm install react-data-export` keeps getting 0.6.0 (`latest`) until 1.0.0 is final. + +Pre mode is Changesets 3's own format. `.changeset/pre.json` holds just `{ "mode": "pre", "tag": "" }`. `changeset version` moves the changesets it consumed into `.changeset/pre/`, where later prereleases skip them and the final release picks them all up again. Don't edit or delete the files in `.changeset/pre/` by hand. + +Any version with a prerelease part (`-alpha.1`, `-beta.0`, ...) is published with `--tag next` and marked as a prerelease on GitHub. A plain version (`1.0.0`) goes to `latest`. + +### Entering pre mode + +```sh +npx changeset pre enter alpha # writes .changeset/pre.json; commit it +npm run version-packages # 1.0.0-alpha.0, then alpha.1, alpha.2, ... +``` + +### Switching the tag (alpha → beta → rc) + +`changeset pre enter` refuses to run while in pre mode, so a tag switch is a one-line edit: + +1. On a branch, change `"tag"` in `.changeset/pre.json` (for example `"alpha"` → `"beta"`). Change nothing else, and don't bump the version. Open a pull request with that change. Merging it publishes nothing, because the version doesn't change. +2. Cut the next release pull request as usual (§2), with at least one pending changeset. + +Changesets numbers the next prerelease from the current version (`prerelease[1] + 1`) and keeps counting across a tag switch: on its own, `changeset version` turns `1.0.0-alpha.3` into `1.0.0-beta.4`. `npm run version-packages` therefore runs `scripts/reset-pre-counter.mjs` right after it. The script compares the package version with the one committed at `HEAD`. When the prerelease tag differs, it rewrites the new version to `-.0` in every changed `package.json` (the package itself and the workspaces that depend on it, such as the playground) and in the `CHANGELOG.md` heading. The `version` constant sync and the lockfile update then use that version. So the release after `1.0.0-alpha.3` is `1.0.0-beta.0`, and the ones after it are `beta.1`, `beta.2`, .... A release with the same tag, a first prerelease and a final version are left alone. + +`scripts/reset-pre-counter.mjs` and its test are copied verbatim from javascript-excel (they are shared by the spreadsheet-family repositories); change them there and in every copy, or not at all. + +Checked with a dry run (2026-11-17): on top of the switch to `"beta"`, one patch changeset and `npm run version-packages` give `1.0.0-beta.0` in `packages/react-data-export/package.json`, `CHANGELOG.md` (`## 1.0.0-beta.0`), the `version` constant, the playground's dependency on the package, and `package-lock.json`. + +### Exiting pre mode (the final 1.0.0) ```sh -npx changeset pre enter alpha # or beta / rc; commit .changeset/pre.json -npm run version-packages # 1.0.0-alpha.1, 1.0.0-alpha.2, ... -npx changeset pre exit # when the final 1.0.0 is next +git switch -c release-1.0.0 origin/main +npx changeset pre exit # sets "mode": "exit" in .changeset/pre.json npm run version-packages # 1.0.0 ``` -Any version with a prerelease part (`-alpha.1`, `-beta.0`, ...) is published with `--tag next` and marked as a prerelease on GitHub. A plain version (`1.0.0`) goes to `latest`. +With `"mode": "exit"`, `changeset version`: + +- versions the package to the plain `1.0.0` (the reset script leaves final versions alone), +- writes one `## 1.0.0` CHANGELOG section with **every** changeset since pre mode was entered: those in `.changeset/pre/` and the new ones, +- deletes `.changeset/pre.json` and all of `.changeset/pre/`. + +Dry run (2026-11-17, from `1.0.0-alpha.3`, with one extra patch changeset): `1.0.0`, `pre.json` and the 8 files in `.changeset/pre/` deleted, and all 9 entries in `## 1.0.0`, under "Minor Changes" and "Patch Changes". None of them is a major bump, because the prereleases were the baseline. Before merging the stable release pull request, add a short hand-written summary of the breaking changes from 0.x at the top of the `## 1.0.0` section (the clean break, `react-data-export/legacy`, the migration guide). The release notes are that section. + +Merging that pull request publishes `1.0.0` to `latest`. The prerelease versions stay on npm under `next`. ## 4. What happens on merge diff --git a/package.json b/package.json index 2d75d58..b95c4b7 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,7 @@ "lint:pkg": "npm run lint:pkg -w react-data-export", "smoke": "node scripts/smoke.mjs", "consumer-ts": "node scripts/consumer-ts.mjs", - "version-packages": "changeset version && node scripts/sync-version.mjs --package packages/react-data-export --file packages/react-data-export/src/index.ts && npm install --package-lock-only --no-audit --no-fund", + "version-packages": "changeset version && node scripts/reset-pre-counter.mjs --package packages/react-data-export && node scripts/sync-version.mjs --package packages/react-data-export --file packages/react-data-export/src/index.ts && npm install --package-lock-only --no-audit --no-fund", "test:release": "node --test \"scripts/*.test.mjs\"", "bundlers": "node scripts/bundlers.mjs", "conformance:sync": "node scripts/sync-jse-corpus.mjs" diff --git a/scripts/reset-pre-counter.mjs b/scripts/reset-pre-counter.mjs new file mode 100644 index 0000000..ec74e5d --- /dev/null +++ b/scripts/reset-pre-counter.mjs @@ -0,0 +1,123 @@ +#!/usr/bin/env node +// Restarts the prerelease counter at 0 when the prerelease tag changes. +// +// Changesets 3 computes the next prerelease number from the package's current +// version (`prerelease[1] + 1`) and keeps counting when the tag in +// `.changeset/pre.json` changes. Switching from alpha to beta after +// 2.0.0-alpha.7 therefore gives 2.0.0-beta.8. `npm run version-packages` runs +// this right after `changeset version`: +// +// node scripts/reset-pre-counter.mjs --package +// +// It compares /package.json's version with the one committed at HEAD. +// When both are prereleases of the form -. and the tag +// differs, it rewrites the new version to -.0 in: +// - every package.json that has uncommitted changes (the package's own +// "version" and any dependency on it, with or without ^, ~ or workspace:), +// - the "## " heading of /CHANGELOG.md. +// The version constant sync and the lockfile update run after it. A release +// with the same tag (alpha.7 -> alpha.8), a first prerelease (1.0.3 -> +// 2.0.0-alpha.0) or a final version (2.0.0) is left alone. Running it again is +// a no-op. +// +// Node built-ins and git only. Shared verbatim by the spreadsheet-family +// repositories; change it in all of them or not at all. + +import { execFileSync } from "node:child_process"; +import { readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { pathToFileURL } from "node:url"; + +const PRERELEASE = /^(\d+\.\d+\.\d+)-([0-9A-Za-z-]+)\.(\d+)$/; + +/** Parse "2.0.0-beta.8" into { base, tag, n }, or null for anything else. */ +export function parsePrerelease(version) { + const m = PRERELEASE.exec(String(version ?? "")); + return m ? { base: m[1], tag: m[2], n: Number(m[3]) } : null; +} + +/** + * The version `next` should be, given the `previous` (committed) version. + * @returns {string | null} the reset version, or null when nothing changes. + */ +export function resetVersion(previous, next) { + const before = parsePrerelease(previous); + const after = parsePrerelease(next); + if (!before || !after || before.tag === after.tag || after.n === 0) return null; + return `${after.base}-${after.tag}.0`; +} + +function escapeRegExp(s) { + return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); +} + +/** Replace `"from"` (optionally prefixed with workspace:, ^ or ~) as a JSON string value. */ +export function rewritePackageJson(text, from, to) { + const pattern = new RegExp(`"((?:workspace:)?[\\^~]?)${escapeRegExp(from)}"`, "g"); + return String(text).replace(pattern, (_m, prefix) => `"${prefix}${to}"`); +} + +/** Replace the one "## from" heading. Fails unless there is exactly one. */ +export function rewriteChangelog(text, from, to) { + const pattern = new RegExp(`^## ${escapeRegExp(from)}[ \\t]*$`, "gm"); + const count = [...String(text).matchAll(pattern)].length; + if (count !== 1) throw new Error(`expected exactly one "## ${from}" heading in CHANGELOG.md, found ${count}`); + return String(text).replace(pattern, `## ${to}`); +} + +function git(args) { + return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }); +} + +function parseArgs(argv) { + const args = { package: null }; + for (let i = 0; i < argv.length; i++) { + if (argv[i] === "--package") args.package = argv[++i]; + else throw new Error(`unknown argument: ${argv[i]}`); + } + if (!args.package) throw new Error("usage: reset-pre-counter.mjs --package "); + return args; +} + +export function main(argv = process.argv.slice(2), { readCommitted = (path) => git(["show", `HEAD:${path}`]), changedFiles } = {}) { + const args = parseArgs(argv); + const pkgPath = join(args.package, "package.json"); + const next = JSON.parse(readFileSync(pkgPath, "utf8")).version; + let previous; + try { + previous = JSON.parse(readCommitted(pkgPath.split("\\").join("/"))).version; + } catch { + console.log(`${pkgPath}: not committed at HEAD; prerelease counter left alone`); + return { changed: false, version: next }; + } + const target = resetVersion(previous, next); + if (target == null) { + console.log(`${pkgPath}: ${previous} -> ${next}; prerelease counter left alone`); + return { changed: false, version: next }; + } + const files = (changedFiles ?? (() => git(["diff", "--name-only", "--", "*package.json"]).split("\n").filter(Boolean)))(); + const touched = []; + for (const file of files) { + const before = readFileSync(file, "utf8"); + const after = rewritePackageJson(before, next, target); + if (after !== before) { + writeFileSync(file, after); + touched.push(file); + } + } + if (!touched.includes(pkgPath)) throw new Error(`${pkgPath} was not rewritten; is it in the list of changed files?`); + const changelog = join(args.package, "CHANGELOG.md"); + writeFileSync(changelog, rewriteChangelog(readFileSync(changelog, "utf8"), next, target)); + touched.push(changelog); + console.log(`prerelease tag changed (${previous} -> ${next}): counter reset to ${target} in ${touched.join(", ")}`); + return { changed: true, version: target, files: touched }; +} + +if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) { + try { + main(); + } catch (err) { + console.error(`reset-pre-counter: ${err instanceof Error ? err.message : err}`); + process.exit(1); + } +} diff --git a/scripts/reset-pre-counter.test.mjs b/scripts/reset-pre-counter.test.mjs new file mode 100644 index 0000000..9fc4934 --- /dev/null +++ b/scripts/reset-pre-counter.test.mjs @@ -0,0 +1,157 @@ +// Tests for scripts/reset-pre-counter.mjs. Run: node --test "scripts/*.test.mjs" +import assert from "node:assert/strict"; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { describe, it } from "node:test"; +import { main, parsePrerelease, resetVersion, rewriteChangelog, rewritePackageJson } from "./reset-pre-counter.mjs"; + +describe("parsePrerelease", () => { + it("parses -.", () => { + assert.deepEqual(parsePrerelease("2.0.0-beta.8"), { base: "2.0.0", tag: "beta", n: 8 }); + }); + it("returns null for final versions and other shapes", () => { + assert.equal(parsePrerelease("2.0.0"), null); + assert.equal(parsePrerelease("2.0.0-beta"), null); + assert.equal(parsePrerelease("2.0.0-beta.1.2"), null); + assert.equal(parsePrerelease(undefined), null); + }); +}); + +describe("resetVersion", () => { + it("resets the counter when the tag changes", () => { + assert.equal(resetVersion("2.0.0-alpha.7", "2.0.0-beta.8"), "2.0.0-beta.0"); + assert.equal(resetVersion("2.0.0-beta.3", "2.0.0-rc.4"), "2.0.0-rc.0"); + }); + it("leaves a same-tag release alone", () => { + assert.equal(resetVersion("2.0.0-alpha.7", "2.0.0-alpha.8"), null); + }); + it("leaves a first prerelease and a final version alone", () => { + assert.equal(resetVersion("1.0.3", "2.0.0-alpha.0"), null); + assert.equal(resetVersion("2.0.0-beta.4", "2.0.0"), null); + }); + it("is a no-op once reset", () => { + assert.equal(resetVersion("2.0.0-alpha.7", "2.0.0-beta.0"), null); + }); +}); + +describe("rewritePackageJson", () => { + it("rewrites the version and dependencies, keeping range prefixes and formatting", () => { + const src = '{\n "name": "x",\n "version": "2.0.0-beta.8",\n "dependencies": {\n "a": "2.0.0-beta.8",\n "b": "^2.0.0-beta.8",\n "c": "~2.0.0-beta.8",\n "d": "workspace:^2.0.0-beta.8"\n }\n}\n'; + assert.equal( + rewritePackageJson(src, "2.0.0-beta.8", "2.0.0-beta.0"), + '{\n "name": "x",\n "version": "2.0.0-beta.0",\n "dependencies": {\n "a": "2.0.0-beta.0",\n "b": "^2.0.0-beta.0",\n "c": "~2.0.0-beta.0",\n "d": "workspace:^2.0.0-beta.0"\n }\n}\n', + ); + }); + it("does not touch other versions or longer versions that contain it", () => { + const src = '{ "a": "2.0.0-beta.80", "b": "12.0.0-beta.8", "c": "1.0.0" }'; + assert.equal(rewritePackageJson(src, "2.0.0-beta.8", "2.0.0-beta.0"), src); + }); +}); + +describe("rewriteChangelog", () => { + it("rewrites only the matching heading", () => { + const src = "# pkg\n\n## 2.0.0-beta.8\n\n- see 2.0.0-beta.8\n\n## 2.0.0-alpha.7\n"; + assert.equal(rewriteChangelog(src, "2.0.0-beta.8", "2.0.0-beta.0"), "# pkg\n\n## 2.0.0-beta.0\n\n- see 2.0.0-beta.8\n\n## 2.0.0-alpha.7\n"); + }); + it("fails without exactly one heading", () => { + assert.throws(() => rewriteChangelog("# pkg\n", "2.0.0-beta.8", "2.0.0-beta.0"), /found 0/); + }); +}); + +describe("main", () => { + function fixture(version, { changelog = `# p\n\n## ${version}\n\n- x\n` } = {}) { + const dir = mkdtempSync(join(tmpdir(), "reset-pre-counter-")); + mkdirSync(join(dir, "packages", "p"), { recursive: true }); + mkdirSync(join(dir, "apps", "a"), { recursive: true }); + const pkg = join(dir, "packages", "p", "package.json"); + const app = join(dir, "apps", "a", "package.json"); + writeFileSync(pkg, `{\n "name": "p",\n "version": "${version}"\n}\n`); + writeFileSync(app, `{\n "name": "a",\n "dependencies": { "p": "${version}" }\n}\n`); + writeFileSync(join(dir, "packages", "p", "CHANGELOG.md"), changelog); + return { dir, pkg, app, changelog: join(dir, "packages", "p", "CHANGELOG.md") }; + } + const quiet = (fn) => { + const log = console.log; + console.log = () => {}; + try { + return fn(); + } finally { + console.log = log; + } + }; + + it("resets every changed file when the tag changed", () => { + const f = fixture("2.0.0-beta.8"); + try { + const r = quiet(() => + main(["--package", join(f.dir, "packages", "p")], { + readCommitted: () => '{ "version": "2.0.0-alpha.7" }', + changedFiles: () => [f.pkg, f.app], + }), + ); + assert.equal(r.version, "2.0.0-beta.0"); + assert.match(readFileSync(f.pkg, "utf8"), /"version": "2.0.0-beta.0"/); + assert.match(readFileSync(f.app, "utf8"), /"p": "2.0.0-beta.0"/); + assert.match(readFileSync(f.changelog, "utf8"), /^## 2.0.0-beta.0$/m); + } finally { + rmSync(f.dir, { recursive: true, force: true }); + } + }); + + it("changes nothing for a same-tag release", () => { + const f = fixture("2.0.0-alpha.8"); + try { + const before = readFileSync(f.pkg, "utf8"); + const r = quiet(() => + main(["--package", join(f.dir, "packages", "p")], { + readCommitted: () => '{ "version": "2.0.0-alpha.7" }', + changedFiles: () => [f.pkg, f.app], + }), + ); + assert.equal(r.changed, false); + assert.equal(readFileSync(f.pkg, "utf8"), before); + } finally { + rmSync(f.dir, { recursive: true, force: true }); + } + }); + + it("changes nothing when the package is not committed yet", () => { + const f = fixture("2.0.0-beta.8"); + try { + const r = quiet(() => + main(["--package", join(f.dir, "packages", "p")], { + readCommitted: () => { + throw new Error("fatal: path not in HEAD"); + }, + changedFiles: () => [f.pkg], + }), + ); + assert.equal(r.changed, false); + } finally { + rmSync(f.dir, { recursive: true, force: true }); + } + }); + + it("fails when the package's own package.json is not among the changed files", () => { + const f = fixture("2.0.0-beta.8"); + try { + assert.throws( + () => + quiet(() => + main(["--package", join(f.dir, "packages", "p")], { + readCommitted: () => '{ "version": "2.0.0-alpha.7" }', + changedFiles: () => [f.app], + }), + ), + /was not rewritten/, + ); + } finally { + rmSync(f.dir, { recursive: true, force: true }); + } + }); + + it("rejects unknown arguments", () => { + assert.throws(() => main(["--file", "x"]), /unknown argument/); + }); +});