Versioning

Version your package, declare its peers, and keep apps on older CLIs working.

Pick a version

Version your package with semver: a major version for a breaking change, a minor version for a new feature, and a patch for a fix.

bash
# 1.0.0 -> 2.0.0: a breaking change
npm version major
# 1.0.0 -> 1.1.0: a new feature
npm version minor
# 1.0.0 -> 1.0.1: a fix
npm version patch

Before 1.0.0, npm treats each minor version as breaking: an app that asks for ^0.6.0 never gets 0.7.0. Bump the minor version for a breaking change, and the patch for anything else.
Ship a codemod with each breaking change so apps can migrate; see astryx docs cli/integrations/building-blocks/codemods.

Know what breaks apps

A breaking change stops code, commands, or links that worked in an app from working after the upgrade. For an integration, these names are part of its API.

You change or remove	What stops working in the app
A component name, such as `AcmeCarousel`	Imports, and `npx astryx component AcmeCarousel`
A template id, such as `acme-dashboard`	`npx astryx template acme-dashboard`
A theme slug, such as `ocean`	`npx astryx theme add ocean`
A topic name or route, such as `acme/deploying`	Reads of the old name, and links to it from other docs
A component's `import` path	Imports written from the old path
An `exports` entry	Imports of that path, which fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`
A prop	`Code` that passes it

List each breaking change in your release notes, with the codemod that migrates it. Any changelog tool works. If package.json has a files allowlist, add CHANGELOG.md to it so npm packs it.

Declare peer ranges

Declare the Astryx packages that your code imports as peer dependencies, in peerDependencies, so the app installs one copy of each. Keep each range as wide as your tests prove.

Peer	Declare it when	Range
`@astryxdesign/core`	Your code imports Core, as a theme does with `@astryxdesign/core/theme`	The Core versions you test, such as `^0.6.0`
`@astryxdesign/theme-*`	Your code imports that theme package	The versions you test
`@astryxdesign/cli`	You ship a docs section, a placed guide, a template that sets `replaces`, a doc section with an `id`, or a theme	`>=0.7.0`, optional in `peerDependenciesMeta`

json
{
  "peerDependencies": {
    "@astryxdesign/core": "^0.6.0",
    "@astryxdesign/cli": ">=0.7.0"
  },
  "peerDependenciesMeta": {
    "@astryxdesign/cli": {"optional": true}
  }
}

integration verify fails a package that needs the CLI peer and lacks it, or whose range admits a stable CLI before 0.7.0. integration add doc --parent and integration add theme write the peer for you.

Support older CLIs

An app may run an older CLI than the one you build with. A CLI reads what it knows and skips the rest, but some newer files make an older CLI hide your docs.

An unknown field in astryx.integration.mjs is ignored with an unknown_manifest_key warning, and the rest of the manifest still loads.
A named export that the CLI does not know is ignored with no warning, so debug and gapReport are safe to add.
A stable CLI before 0.7.0 prints each {@link ...} as written.
A stable CLI before 0.7.0 cannot read a docs section, a section id, a template that sets replaces, or a theme folder that integration add theme writes. It can then hide every doc topic your package ships.
Stable 0.6.3 still loads your components, but 0.6.0 cannot read the component docs that integration add component writes: component AcmeCarousel fails there.

integration verify requires the CLI peer for a docs section, a placed guide, a template replaces, a doc section with an id, and a theme. A stable CLI before 0.7.0 cannot read any of them, and when it hides your topics, docs gives no warning.

Name codemod folders after Core versions

Name each codemod folder after the Core version whose upgrade should run it, not after your package's version. Which folders an app runs, and when, is in "Choose when a codemod runs" in astryx docs cli/integrations/building-blocks/codemods.