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.mdindex 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 cutdiff --git a/scripts/changeset-new.mjs b/scripts/changeset-new.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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);+ });+});