An open source design system that's fully customizable and agent ready
TypeScript
feat: add experimental changeset category (#6705)
Cindy Zhang395846ba4ff4
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex bddf5c5864..820dbbf581 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -562,9 +562,9 @@ pnpm changeset:newThis 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.+2. **Asks for a category** (`breaking`, `experimental`, `component`, `feat`, `fix`, `perf`, `docs`, `chore`) — this drives changelog grouping and the pre-1.0 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. **Derives the semver bump from the category** — a `[breaking]` change bumps the minor; everything else bumps the patch (see below).+4. **Derives the semver bump from the category** — a `[breaking]` change bumps the minor; `[experimental]` and every other category bump the patch (see below).It writes a normal `.changeset/<id>.md` — commit it with your PR. The body looks like:@@ -587,11 +587,12 @@ pnpm changeset:new --category fix --summary "…" --pr 2717 --contributor yourha> convention by hand (`[category]` first line + `@handle` line). CI> (`pnpm check:changesets`) rejects changesets missing a category or> contributor, or whose bump doesn't match the category (`[breaking]` must be-> `minor`, everything else `patch`), or declaring a `major` bump while 0.x.+> `minor`; `[experimental]` and every other category must be `patch`), or+> declaring a `major` bump while 0.x.### Version Bumps-- **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.+- **0.x (current): bump follows the category.** We track standard semver for the `0.x.y` range, where a minor bump is the stable breaking tier (under a caret range like `^0.1.8`, npm resolves `<0.2.0`). A `[breaking]` change bumps the **minor** (`0.x.y → 0.(x+1).0`). A change confined to a surface that was explicitly marked experimental before its first stable publication uses `[experimental]` and bumps the **patch**, even when that experimental API changes incompatibly. Every other category (`feat`, `fix`, `component`, `perf`, `docs`, `chore`) also bumps the patch. If stable defaults, behavior, props, imports, CLI commands, or machine schemas break, the change remains `[breaking]`. `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` 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-entry-format.cjs b/scripts/changeset-entry-format.cjsindex 53d5c72f8b..0a77c2dfdd 100644--- a/scripts/changeset-entry-format.cjs+++ b/scripts/changeset-entry-format.cjs@@ -31,6 +31,7 @@// changelog. `label` is the changelog section heading.const CATEGORIES = [{key: 'breaking', label: 'Breaking Changes'},+ {key: 'experimental', label: 'Experimental APIs'},{key: 'component', label: 'New Components'},{key: 'feat', label: 'New Features'},{key: 'fix', label: 'Fixes'},diff --git a/scripts/changeset-new.mjs b/scripts/changeset-new.mjsindex a0876f7734..9d3c2cf439 100755--- a/scripts/changeset-new.mjs+++ b/scripts/changeset-new.mjs@@ -13,8 +13,9 @@* rest so versions stay aligned without polluting their changelogs.* 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.+ * caret ranges); every other category, including [experimental], 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.@@ -24,7 +25,7 @@* scripts/check-changesets.mjs.** Flags (all optional; missing values are prompted):- * --category <key> breaking|component|feat|fix|perf|docs|chore+ * --category <key> breaking|experimental|component|feat|fix|perf|docs|chore* --summary <text> one-line headline* --contributor <h> repeatable; defaults to detected identity* --pr <number> PR number (appended as (#n) if not already in summary)diff --git a/scripts/check-changesets.mjs b/scripts/check-changesets.mjsindex 30f60c2984..44b21c8883 100755--- a/scripts/check-changesets.mjs+++ b/scripts/check-changesets.mjs@@ -7,7 +7,8 @@* 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).+ * category, including [experimental], 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.@@ -163,7 +164,7 @@ function main() {process.exit(1);}console.log(- `✓ check:changesets — ${files.length} changeset(s) valid${ctx.pre1 ? ' (0.x: [breaking] -> minor, else patch)' : ''}`,+ `✓ check:changesets — ${files.length} changeset(s) valid${ctx.pre1 ? ' (0.x: [breaking] -> minor, [experimental] and other categories -> patch)' : ''}`,);}diff --git a/scripts/check-changesets.test.mjs b/scripts/check-changesets.test.mjsindex 9ad68ae8fb..af82e5297f 100644--- a/scripts/check-changesets.test.mjs+++ b/scripts/check-changesets.test.mjs@@ -3,8 +3,9 @@/*** @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.+ * coupling: a [breaking] change must bump the minor, [experimental] and every+ * other non-breaking category must bump the patch, and major is rejected while+ * pre-1.0.*/import {describe, it, expect} from 'vitest';@@ -35,7 +36,34 @@ describe('validateChangeset — 0.x semver coupling', () => {expect(problems).toEqual([]);});- it('accepts a non-breaking category with a patch bump', () => {+ it('accepts an incompatible experimental-only change with a patch bump', () => {+ const problems = validateChangeset(+ 'a.md',+ cs(+ "'@astryxdesign/core': patch",+ '[experimental] Rename an experimental callback (#1)\n@who',+ ),+ ctx,+ );+ expect(problems).toEqual([]);+ });++ it('rejects [experimental] declared as minor', () => {+ const problems = validateChangeset(+ 'a.md',+ cs(+ "'@astryxdesign/core': minor",+ '[experimental] Remove an experimental prop (#1)\n@who',+ ),+ ctx,+ );+ expect(problems).toHaveLength(1);+ expect(problems[0]).toMatch(+ /declares "minor".*category is \[experimental\].*Use "patch"/,+ );+ });++ it('accepts another non-breaking category with a patch bump', () => {for (const category of ['feat','fix',diff --git a/scripts/format-changelogs.mjs b/scripts/format-changelogs.mjsindex a3d4c3c936..5bff74265a 100755--- a/scripts/format-changelogs.mjs+++ b/scripts/format-changelogs.mjs@@ -21,6 +21,9 @@* #### Breaking Changes (h4 category sections, canonical order)* - Stack element -> as (#2441)*+ * #### Experimental APIs+ * - Rename an experimental callback (#2442)+ ** #### Fixes* - XDSButton: spinner contrast (#2717)*diff --git a/scripts/format-changelogs.test.mjs b/scripts/format-changelogs.test.mjsindex 27ff5db269..ed8b054e05 100644--- a/scripts/format-changelogs.test.mjs+++ b/scripts/format-changelogs.test.mjs@@ -81,6 +81,25 @@ describe('reflowBulletBody', () => {});describe('formatVersionBlock line-wrapping', () => {+ it('groups experimental entries separately after breaking changes', () => {+ const body = [+ '### Patch Changes',+ '',+ '- [fix] Preserve the stable path. — thanks @athz',+ '- [experimental] Rename an experimental callback. — thanks @cixzhang',+ '- [breaking] Remove a stable callback. — thanks @joeyfarina',+ ].join('\n');+ const out = formatVersionBlock('0.9.9', body);++ expect(out).toContain('#### Experimental APIs');+ expect(out.indexOf('#### Breaking Changes')).toBeLessThan(+ out.indexOf('#### Experimental APIs'),+ );+ expect(out.indexOf('#### Experimental APIs')).toBeLessThan(+ out.indexOf('#### Fixes'),+ );+ });+it('normalizes wrapping across entries so hard-wrapped and single-line prose match', () => {const body = ['### Patch Changes',