Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(release): bump the minor for breaking changes while 0.x (#4264)

EJ Hammondede1ea177d3e
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b0fc9d6244..671d73e229 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -342,7 +342,7 @@ This wrapper:
1. **Detects which packages you changed** from your git diff and pre-selects them — no hand-enumerating the frontmatter.
2. **Asks for a category** (`breaking`, `component`, `feat`, `fix`, `perf`, `docs`, `chore`) — this drives changelog grouping, _not_ the semver bump.
3. **Captures the contributor(s)** — defaults to your `gh`/git identity, so credit is recorded at authoring time (not reconstructed from the release bot's commit).
-4. **Forces a `patch` bump** while we're pre-1.0 (see below).
+4. **Derives the semver bump from the category** — a `[breaking]` change bumps the minor; everything else bumps the patch (see below).
It writes a normal `.changeset/<id>.md` — commit it with your PR. The body looks like:
@@ -364,11 +364,12 @@ pnpm changeset:new --category fix --summary "…" --pr 2717 --contributor yourha
> The bare `pnpm changeset` CLI still works, but you must follow the body
> convention by hand (`[category]` first line + `@handle` line). CI
> (`pnpm check:changesets`) rejects changesets missing a category or
-> contributor, or declaring a `minor`/`major` bump while pre-1.0.
+> contributor, or whose bump doesn't match the category (`[breaking]` must be
+> `minor`, everything else `patch`), or declaring a `major` bump while 0.x.
### Version Bumps
-- **Pre-1.0 (current): always `patch`.** The Changesets CLI maps `minor` → 0.0.x → 0.1.0 and `major` → 1.0.0. While we're on 0.0.x we ship every change — features, fixes, and breaking changes alike — as a `patch`. Signal a breaking change with the `[breaking]` **category**, not a `major` bump. `pnpm changeset:new` enforces this; `pnpm check:changesets` is the CI backstop.
+- **0.x (current): bump follows the category.** We track standard semver for the `0.x.y` range, where a minor bump is the breaking tier (under a caret range like `^0.1.8`, npm resolves `<0.2.0`, so `0.1.x → 0.2.0` is what signals "may break you"). A `[breaking]` change bumps the **minor** (`0.x.y → 0.(x+1).0`); every other category (`feat`, `fix`, `component`, `perf`, `docs`, `chore`) bumps the **patch**. `major` is never used while 0.x — it would jump to `1.0.0`. `pnpm changeset:new` writes the right bump from the category you pick; `pnpm check:changesets` is the CI backstop that enforces the coupling both ways.
- All publishable packages are a `fixed` group, so a single change co-bumps them to the same version. Only genuinely-affected packages get a changelog entry — the rest get a clean version-only bump.
### How a release is cut
diff --git a/scripts/changeset-new.mjs b/scripts/changeset-new.mjs
index d7c5ebf34a..a0876f7734 100755
--- a/scripts/changeset-new.mjs
+++ b/scripts/changeset-new.mjs
@@ -11,8 +11,10 @@
* so you don't hand-enumerate the frontmatter. Only genuinely-affected
* packages get the changelog entry; the `fixed` lockstep co-bumps the
* rest so versions stay aligned without polluting their changelogs.
- * 2. semver vs v0 — forces `patch` while the repo is < 1.0. No way to
- * accidentally author a `minor` that jumps 0.0.x -> 0.1.0.
+ * 2. semver for 0.x — derives the bump from the category. A [breaking]
+ * change bumps the minor (0.x.y -> 0.(x+1).0, the breaking tier under
+ * caret ranges); everything else bumps the patch. No way to declare a
+ * mismatched bump by hand — check-changesets.mjs enforces the coupling.
* 3. Contributor encapsulation — captures the human contributor(s) at
* authoring time (defaulting to your `gh` / git identity) and writes them
* into the changeset body, where the custom changelog module reads them.
@@ -249,8 +251,12 @@ async function main() {
if (prNum && !/\(#\d+\)/.test(headline)) headline += ` (#${prNum})`;
const body = `[${catKey}] ${headline}\n${contributors.map(c => '@' + c).join(' ')}`;
- // ---- bump (patch-only pre-1.0) ----------------------------------------
- const bump = 'patch'; // intentionally patch; minor/major gated by checker pre-1.0
+ // ---- bump (derived from category: [breaking] -> minor, else patch) ----
+ // Under 0.x caret ranges (^0.1.8 allows <0.2.0) a minor bump is the
+ // breaking tier, so breaking changes bump the minor and everything else
+ // bumps the patch. major is never used pre-1.0 (it would jump to 1.0.0).
+ // check-changesets.mjs enforces this coupling both ways.
+ const bump = catKey === 'breaking' ? 'minor' : 'patch';
const frontmatter = selected.map(n => `'${n}': ${bump}`).join('\n');
// ---- filename (human-id style without the dep) ------------------------
@@ -268,7 +274,12 @@ async function main() {
console.log(`\n✓ Wrote ${path.relative(ROOT, file)}\n`);
console.log(contents);
- if (pre1) console.log('(pre-1.0: bump forced to patch)');
+ if (pre1)
+ console.log(
+ bump === 'minor'
+ ? '(0.x: [breaking] -> minor bump)'
+ : '(0.x: bump -> patch)',
+ );
}
main().catch(e => {
diff --git a/scripts/check-changesets.mjs b/scripts/check-changesets.mjs
index 952ffe4aa3..30f60c2984 100755
--- a/scripts/check-changesets.mjs
+++ b/scripts/check-changesets.mjs
@@ -4,9 +4,10 @@
* CI gate for XDS changesets — `node scripts/check-changesets.mjs`.
*
* Enforces the conventions the release process depends on:
- * 1. Pre-1.0 patch-only: while every publishable package is < 1.0.0, no
- * changeset may declare a `minor` or `major` bump (would jump 0.0.x ->
- * 0.1.0 / 1.0.0).
+ * 1. 0.x semver coupling: while every publishable package is < 1.0.0, the
+ * bump must match the category. A [breaking] changeset must be `minor`
+ * (0.x.y -> 0.(x+1).0, the breaking tier under caret ranges); every other
+ * category must be `patch`. `major` is rejected (it would jump to 1.0.0).
* 2. Every changeset body must carry a recognized [category] tag.
* 3. Every changeset body must credit at least one @contributor.
* 4. Frontmatter packages must be real, publishable, non-ignored packages.
@@ -59,62 +60,98 @@ function isChangesetFile(name) {
return name.endsWith('.md') && !SKIP.has(name);
}
+/**
+ * Validate one changeset's contents against the conventions. Pure and
+ * side-effect-free so it can be unit-tested without the filesystem.
+ *
+ * @param {string} file display name (for messages)
+ * @param {string} contents raw changeset markdown
+ * @param {object} ctx {pre1, pubNames:Set, allNames:Set}
+ * @returns {string[]} list of human-readable problems (empty = valid)
+ */
+function validateChangeset(file, contents, ctx) {
+ const {pre1, pubNames, allNames} = ctx;
+ const problems = [];
+
+ const fm = parseFrontmatter(contents);
+ if (!fm) {
+ problems.push(`${file}: missing or invalid frontmatter`);
+ return problems;
+ }
+ if (Object.keys(fm.releases).length === 0)
+ problems.push(`${file}: frontmatter lists no packages`);
+
+ // Parse the body first: while 0.x the required bump is derived from the
+ // [category] — [breaking] -> minor, everything else -> patch.
+ const parsed = parseEntry(fm.summary);
+ const expected = parsed.category === 'breaking' ? 'minor' : 'patch';
+
+ for (const [name, type] of Object.entries(fm.releases)) {
+ if (!allNames.has(name)) {
+ problems.push(`${file}: unknown package "${name}"`);
+ } else if (!pubNames.has(name)) {
+ problems.push(
+ `${file}: "${name}" is private/ignored and cannot be released`,
+ );
+ }
+ if (!['major', 'minor', 'patch', 'none'].includes(type)) {
+ problems.push(`${file}: "${name}" has invalid bump "${type}"`);
+ } else if (pre1 && type === 'major') {
+ problems.push(
+ `${file}: "${name}" declares "major" — repo is 0.x, which has no major ` +
+ `bump (it would jump to 1.0.0). Use [breaking] (minor) instead.`,
+ );
+ } else if (
+ pre1 &&
+ parsed.category &&
+ type !== 'none' &&
+ type !== expected
+ ) {
+ // Coupling: while 0.x, the bump must match the category both ways.
+ problems.push(
+ expected === 'minor'
+ ? `${file}: "${name}" is a [breaking] change but declares "${type}" — ` +
+ `breaking changes bump the minor while 0.x (0.x.y -> 0.(x+1).0). Use "minor".`
+ : `${file}: "${name}" declares "minor" but the category is [${parsed.category}] — ` +
+ `only [breaking] changes bump the minor while 0.x. Use "patch", ` +
+ `or change the category to [breaking] if this is a breaking change.`,
+ );
+ }
+ }
+
+ if (!parsed.category) {
+ problems.push(
+ `${file}: body must start with a [category] tag, e.g. "[fix] ...". ` +
+ `Run \`pnpm changeset:new\` to author one correctly.`,
+ );
+ }
+ if (!parsed.headline) problems.push(`${file}: body has no summary headline`);
+ if (parsed.contributors.length === 0) {
+ problems.push(
+ `${file}: body must credit at least one contributor, e.g. "@yourhandle" ` +
+ `on its own line. Run \`pnpm changeset:new\`.`,
+ );
+ }
+ return problems;
+}
+
function main() {
const config = readConfig();
const pkgs = discoverPackages();
const pub = pkgs.filter(
p => !p.private && !(config.ignore || []).includes(p.name),
);
- const pubNames = new Set(pub.map(p => p.name));
- const allNames = new Set(pkgs.map(p => p.name));
- const pre1 = pub.every(p => /^0\./.test(String(p.version || '0')));
+ const ctx = {
+ pubNames: new Set(pub.map(p => p.name)),
+ allNames: new Set(pkgs.map(p => p.name)),
+ pre1: pub.every(p => /^0\./.test(String(p.version || '0'))),
+ };
const files = fs.readdirSync(CS_DIR).filter(isChangesetFile);
const problems = [];
-
for (const f of files) {
const contents = fs.readFileSync(path.join(CS_DIR, f), 'utf8');
- const fm = parseFrontmatter(contents);
- if (!fm) {
- problems.push(`${f}: missing or invalid frontmatter`);
- continue;
- }
- const names = Object.keys(fm.releases);
- if (names.length === 0)
- problems.push(`${f}: frontmatter lists no packages`);
- for (const [name, type] of Object.entries(fm.releases)) {
- if (!allNames.has(name)) {
- problems.push(`${f}: unknown package "${name}"`);
- } else if (!pubNames.has(name)) {
- problems.push(
- `${f}: "${name}" is private/ignored and cannot be released`,
- );
- }
- if (pre1 && (type === 'minor' || type === 'major')) {
- problems.push(
- `${f}: "${name}" declares "${type}" — repo is pre-1.0, use "patch" ` +
- `(minor/major would jump 0.0.x). Use [breaking] in the body to signal a breaking change.`,
- );
- }
- if (!['major', 'minor', 'patch', 'none'].includes(type)) {
- problems.push(`${f}: "${name}" has invalid bump "${type}"`);
- }
- }
-
- const parsed = parseEntry(fm.summary);
- if (!parsed.category) {
- problems.push(
- `${f}: body must start with a [category] tag, e.g. "[fix] ...". ` +
- `Run \`pnpm changeset:new\` to author one correctly.`,
- );
- }
- if (!parsed.headline) problems.push(`${f}: body has no summary headline`);
- if (parsed.contributors.length === 0) {
- problems.push(
- `${f}: body must credit at least one contributor, e.g. "@yourhandle" ` +
- `on its own line. Run \`pnpm changeset:new\`.`,
- );
- }
+ problems.push(...validateChangeset(f, contents, ctx));
}
if (problems.length) {
@@ -126,8 +163,13 @@ function main() {
process.exit(1);
}
console.log(
- `✓ check:changesets — ${files.length} changeset(s) valid${pre1 ? ' (pre-1.0 patch-only enforced)' : ''}`,
+ `✓ check:changesets — ${files.length} changeset(s) valid${ctx.pre1 ? ' (0.x: [breaking] -> minor, else patch)' : ''}`,
);
}
-main();
+// Run as a script, but stay importable for unit tests.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+ main();
+}
+
+export {validateChangeset, parseFrontmatter};
diff --git a/scripts/check-changesets.test.mjs b/scripts/check-changesets.test.mjs
new file mode 100644
index 0000000000..9ad68ae8fb
--- /dev/null
+++ b/scripts/check-changesets.test.mjs
@@ -0,0 +1,116 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file check-changesets.test.mjs
+ * Unit tests for the changeset convention gate — specifically the 0.x semver
+ * coupling: a [breaking] change must bump the minor, every other category must
+ * bump the patch, and major is rejected while pre-1.0.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {validateChangeset} from './check-changesets.mjs';
+
+const ctx = {
+ pre1: true,
+ pubNames: new Set(['@astryxdesign/core', '@astryxdesign/cli']),
+ allNames: new Set([
+ '@astryxdesign/core',
+ '@astryxdesign/cli',
+ '@astryxdesign/storybook',
+ ]),
+};
+
+const cs = (frontmatter, body) => `---\n${frontmatter}\n---\n\n${body}\n`;
+
+describe('validateChangeset — 0.x semver coupling', () => {
+ it('accepts [breaking] with a minor bump', () => {
+ const problems = validateChangeset(
+ 'a.md',
+ cs(
+ "'@astryxdesign/core': minor",
+ '[breaking] Rename items to options (#1)\n@who',
+ ),
+ ctx,
+ );
+ expect(problems).toEqual([]);
+ });
+
+ it('accepts a non-breaking category with a patch bump', () => {
+ for (const category of [
+ 'feat',
+ 'fix',
+ 'component',
+ 'perf',
+ 'docs',
+ 'chore',
+ ]) {
+ const problems = validateChangeset(
+ 'a.md',
+ cs("'@astryxdesign/core': patch", `[${category}] Something (#1)\n@who`),
+ ctx,
+ );
+ expect(problems, category).toEqual([]);
+ }
+ });
+
+ it('rejects [breaking] declared as patch', () => {
+ const problems = validateChangeset(
+ 'a.md',
+ cs("'@astryxdesign/core': patch", '[breaking] Remove onHide (#1)\n@who'),
+ ctx,
+ );
+ expect(problems).toHaveLength(1);
+ expect(problems[0]).toMatch(/breaking.*declares "patch".*Use "minor"/);
+ });
+
+ it('rejects a non-breaking category declared as minor', () => {
+ const problems = validateChangeset(
+ 'a.md',
+ cs(
+ "'@astryxdesign/core': minor",
+ '[feat] Add optional size prop (#1)\n@who',
+ ),
+ ctx,
+ );
+ expect(problems).toHaveLength(1);
+ expect(problems[0]).toMatch(/declares "minor".*category is \[feat\]/);
+ });
+
+ it('rejects a major bump while 0.x', () => {
+ const problems = validateChangeset(
+ 'a.md',
+ cs("'@astryxdesign/core': major", '[breaking] Total rewrite (#1)\n@who'),
+ ctx,
+ );
+ expect(problems).toHaveLength(1);
+ expect(problems[0]).toMatch(/declares "major".*no major bump.*1\.0\.0/);
+ });
+
+ it('does not enforce the coupling once past 1.0', () => {
+ const problems = validateChangeset(
+ 'a.md',
+ cs("'@astryxdesign/core': minor", '[feat] Add prop (#1)\n@who'),
+ {...ctx, pre1: false},
+ );
+ expect(problems).toEqual([]);
+ });
+
+ it('still flags a missing category and missing contributor', () => {
+ const problems = validateChangeset(
+ 'a.md',
+ cs("'@astryxdesign/core': patch", 'no category or handle here'),
+ ctx,
+ );
+ expect(problems.some(p => /\[category\] tag/.test(p))).toBe(true);
+ expect(problems.some(p => /contributor/.test(p))).toBe(true);
+ });
+
+ it('flags a private/ignored package', () => {
+ const problems = validateChangeset(
+ 'a.md',
+ cs("'@astryxdesign/storybook': patch", '[fix] x (#1)\n@who'),
+ ctx,
+ );
+ expect(problems.some(p => /private\/ignored/.test(p))).toBe(true);
+ });
+});