An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): define cross-package range compatibility (#5967)
Cindy Zhang29bde32ae833
diff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.mdindex 191e982883..4c3c920482 100644--- a/docs/specs/AST-017/spec.md+++ b/docs/specs/AST-017/spec.md@@ -75,7 +75,12 @@ preserves the released contract.`0.x`, that category carries a minor bump; every nonbreaking published categorycarries a patch bump. Documentation-only, test-only, and private-package-onlychanges need no Changeset. `pnpm changeset:new` is the authoring path and- `pnpm check:changesets` enforces the current category/bump coupling.+ `pnpm check:changesets` enforces the current category/bump coupling. Classify+ each published package update in multi-package work. A fixed-group version-only+ co-bump needs no Changeset entry by itself, but a generated dependency or peer+ range edit is part of that package's update and must be classified and named in a+ Changeset. When categories differ, use separate Changesets so every package entry+ follows its own classification.- **FR8 — Migration evidence matches the affected surface.** Every breaking changenames the old valid usage, the replacement, and how consumers migrate. Supply an`astryx upgrade` codemod when consumer source can be rewritten mechanically.@@ -98,6 +103,17 @@ preserves the released contract.contractual surfaces under FR3. Individual catalog values returned through thatschema, including template slugs, names, descriptions, categories, keywords, andstarter content, are not independently stable API identifiers.+- **FR12 — Supported inter-package ranges are contracts.** For an update to a+ published package, its latest stable release's documented installation scenarios+ and declared dependency or peer ranges define the supported companion package+ versions. The update is breaking for that package when upgrading it alone makes+ any such combination stop working unchanged, including by narrowing or raising+ the range. A coordinated upgrade that works does not change that classification.+ A dependency bump is not breaking when every previously supported combination+ keeps working. Keep every previously supported version in range and provide an+ adapter when needed; otherwise classify the narrower or higher-floor range as+ breaking, describe the range change in its Changeset release note, and meet FR8's+ migration obligation.### Platform support@@ -130,12 +146,13 @@ not the individual entries currently present in the template catalog.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |-| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |-| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |-| FR7–FR8 | `pnpm check:changesets` plus migration review | breaking and patch Changesets; codemoddable and non-codemoddable migration | Category and bump diverge, or a breaking release gives no usable migration path |-| FR9–FR11 | CLI contract tests plus template catalog and output tests | slug rename, metadata edit, source rebuild, command or schema change | Catalog data is frozen as API, or a command/schema incompatibility is mislabeled as a catalog-only edit |+| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |+| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |+| FR7–FR8 | `pnpm check:changesets` plus migration review | breaking and patch Changesets; codemoddable and non-codemoddable migration | Category and bump diverge, or a breaking release gives no usable migration path |+| FR9–FR11 | CLI contract tests plus template catalog and output tests | slug rename, metadata edit, source rebuild, command or schema change | Catalog data is frozen as API, or a command/schema incompatibility is mislabeled as a catalog-only edit |+| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |## Decision log@@ -173,6 +190,23 @@ Rejected: treating a slug as stable API merely because it is interpolated into aexact CLI invocation. That would freeze catalog data and discourage clearer namingwithout protecting a contract the template system intends to make.+### DEC-3 — Package updates keep their own range promises++**Reference:** `spec:AST-017/DEC-3`+**Decider:** `cixzhang`, `2026-09-03`++Treat the latest stable package's declared dependency or peer range and documented+installation scenario as its compatibility promise. Consumers may upgrade that+package with any companion version the range still allows; a coordinated release+cannot require an undeclared lockstep upgrade. Classify the package update that+creates the mismatch. Supporting package updates keep their own classifications.+A coordinated breaking range change remains allowed when its Changeset release note+describes the new range and its FR8 migration tells consumers how to move.++Rejected: marking every dependency bump breaking, which would freeze compatible+maintenance, or calling an update nonbreaking merely because a coordinated upgrade+works, which would break supported independent consumers.+## Open questionsNone.