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
2 changes: 1 addition & 1 deletion .changeset/pre.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"mode": "pre",
"tag": "alpha"
"tag": "beta"
}
47 changes: 40 additions & 7 deletions RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ When a release makes sense (Afzal or the team lead decides):

```sh
git switch -c release-<version> 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
```

Expand All @@ -32,24 +32,57 @@ 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.

Open the pull request. Its **Release dry run** CI job shows what merging would do. The "Release preview" step says which version would be published, or "no release". The job also runs `npm publish --dry-run` with the dist-tag that would be used.

## 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": "<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 `-<tag>.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

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
123 changes: 123 additions & 0 deletions scripts/reset-pre-counter.mjs
Original file line number Diff line number Diff line change
@@ -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 <dir>
//
// It compares <dir>/package.json's version with the one committed at HEAD.
// When both are prereleases of the form <x.y.z>-<tag>.<n> and the tag
// differs, it rewrites the new version to <x.y.z>-<tag>.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 "## <version>" heading of <dir>/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 <dir>");
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);
}
}
157 changes: 157 additions & 0 deletions scripts/reset-pre-counter.test.mjs
Original file line number Diff line number Diff line change
@@ -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 <x.y.z>-<tag>.<n>", () => {
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/);
});
});
Loading