Skip to content

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.md
index bddf5c5864..820dbbf581 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -562,9 +562,9 @@ pnpm changeset:new
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.
+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 cut
diff --git a/scripts/changeset-entry-format.cjs b/scripts/changeset-entry-format.cjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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',