Versioning and stability

Simurgh is currently pre-release. Most packages are at 0.1.0; the CLI may have a different patch version because packages are released independently. Pin exact versions for production use and review release notes and application diffs before every update.

Package versions

Simurgh uses Changesets to record package releases. A change can update only the affected package, so @simurgh-ui/react, @simurgh-ui/styles, and @simurgh-ui/cli are not guaranteed to share the same version number.

During the 0.x pre-release period:

A patch or minor release may contain a breaking public API, rendered DOM, styling-hook, or interaction change.
Release notes must identify breaking changes and the affected adapters or registry components.
Consumers should update the framework adapter and @simurgh-ui/styles together when a release changes both behavior and recipes.
Peer-dependency ranges describe install compatibility, not a guarantee that every version in the range has identical runtime behavior.

The CLI changelog records published CLI changes. Changesets and package changelogs in the repository are the release source of truth until a unified release page is available.

What counts as breaking

A change is breaking when an existing consumer may need to change application code, styling, tests, or usage to preserve behavior. This includes:

Removing or renaming a prop, callback, input, output, event, slot, exported symbol, or package subpath.
Changing a default, controlled/uncontrolled contract, submitted value, emitted payload, or public method.
Changing required compound-component anatomy, rendered semantics, focus order, keyboard behavior, accessible naming, or dismissal behavior.
Removing a documented recipe class, CSS variable, data-* hook, stable DOM part, or theme token.
Changing CLI target paths, generated filenames, configuration shape, or overwrite behavior.

Bug fixes that restore an already documented accessibility contract may alter observable behavior. Release notes should still call out that change even when it is not classified as a breaking API.

Deprecation and breaking-change policy

After 1.0.0, a documented public API must be deprecated before removal. The deprecation remains available for at least 90 calendar days and one published minor release, whichever is longer. Deprecation notices identify the replacement and removal target in types, documentation, and release notes. Removal or another incompatible stable-API change requires a major release.

Before 1.0.0, an incompatible public-API change requires a minor release, a Changeset marked as breaking, release-note migration instructions, and an API-report review. Patch releases must remain compatible. The notice window does not apply to experimental surfaces. A confirmed security issue, legal requirement, or severe accessibility defect may shorten a window when the release notes name the exception, impact, and safest available migration.

Support policy

During pre-release development, only the latest 0.x minor line receives fixes. After 1.0.0, the latest two minor lines receive correctness and accessibility fixes. Security fixes cover those lines and any stable minor released in the previous six months. Browser and framework support follows the tested compatibility matrix; removing a supported major is a breaking change. Older releases remain available but are unsupported.

The machine-readable source for these windows is stability-policy.json, which release checks validate against this guide.

Experimental chart and motion surfaces

Experimental APIs may change or be removed in a minor release without the stable deprecation window. They must still receive a Changeset and migration note; a patch release cannot break them. The explicit experimental package and import namespaces are:

@simurgh-ui/motion
@simurgh-ui/motion/*
@simurgh-ui/core/charts
@simurgh-ui/core/chart-*
@simurgh-ui/react/chart*
@simurgh-ui/vue/chart*
@simurgh-ui/angular/chart*

The wildcard notation describes all published subpaths beginning with that prefix, including framework chart components, interactions, streaming, Canvas, and chart-motion adapters. A chart or motion API becomes stable only when release notes explicitly graduate it and move it to a stable surface; documentation quality or long availability alone does not imply graduation.

Package-consumer policy

Package consumers adopt changes when they update their lockfile. Breaking release notes must include the old contract, new contract, affected packages, and a migration example. Consumers should be able to remain on the previous exact version while migrating; releases must not modify application source automatically.

Validate upgrades with type checking, unit and browser tests, keyboard flows, form submission, RTL, dark mode, and application theme overrides. See Updates and migrations for the complete workflow.

Copied-source policy

CLI-copied components belong to the consuming application. Installing a newer CLI or registry does not update those files. Registry changes become application changes only when the consumer reviews and adopts them.

simurgh diff reports whether a local file matches the selected registry; it is not a semantic migration or merge. simurgh add <component> --overwrite replaces the local file and therefore may remove application customization. Simurgh will preserve existing files by default and requires the explicit overwrite flag for replacement.

When registry behavior changes, release notes must name the affected component and describe any accessibility, API, style-hook, dependency, or configuration migration. Consumers may intentionally remain different from the registry after reviewing and porting only relevant fixes.

Stabilization target

Before a stable 1.0.0, the project should publish complete API and styling contracts, verify its compatibility matrix in CI, and document a deprecation window. Until then, do not assume an undocumented rendered element, class name, or internal helper is stable. Documented public APIs and release notes are the only intended integration contracts.

Last verified on 2026-08-13 against Simurgh registry 0.1.1.