Skip to content

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.md
index 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 category
carries a patch bump. Documentation-only, test-only, and private-package-only
changes 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 change
names 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 that
schema, including template slugs, names, descriptions, categories, keywords, and
starter 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 a
exact CLI invocation. That would freeze catalog data and discourage clearer naming
without 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 questions
None.