Skip to main content

​
How Versioning Works

Anvil2 uses semantic versioning, following the standard three-part version string: MAJOR.MINOR.PATCH

​
Major releases

Indicate breaking changes that may require design or engineering updates. Breaking changes to stable components and features are batched into major releases.

​
Examples

  • Large UI changes affecting multiple components
  • Significant updates to foundational tokens
  • Removing previously deprecated components or features
  • Major changes to API or behavior
Major releases are planned on a quarterly cadence. Announcements are shared approximately three months ahead of the target release window, giving teams time to plan for migration and testing. For major breaking changes, the Anvil team will provide migration guidance at time of release.

​
Minor releases

Add new features while maintaining backwards compatibility. Minor releases ship as needed when feature work is ready.

​
Examples

  • New components or variants
  • Updated interactions
  • Enhancements to patterns
  • Additions to documentation
  • Minor accessibility improvements
Teams can adopt minor releases immediately, as they do not break existing implementations.

​
Patch releases

Contain small, safe, incremental updates. Patch releases ship as needed.

​
Examples

  • Bug fixes
  • Visual polish
  • Icon additions
  • Documentation corrections
  • Minor accessibility fixes
  • Internal code improvements
Teams should adopt patch releases as soon as possible to ensure quality and consistency.
Patch releases may also include breaking changes to beta features. See Beta features below.

​
Consumer compatibility policy

Compatibility for Anvil2 packages is enforced by semver, the TypeScript public API, and review — not by a consumer-contract test suite against every downstream app.

​
When a major, minor, or patch is required

Use a major when a stable consumer must change source, types, or runtime behavior to keep compiling or working after upgrade. Prefer deprecation (see below) before removal so teams can migrate inside the announced window.

​
Deprecation window before removals

Stable APIs are not removed in minor or patch releases.
  • Removals and other breaking stable changes ship in major releases.
  • Major release announcements go out approximately three months ahead of the target window. That lead time is the deprecation window for planned removals and other breaking stable changes.
  • Migration guidance ships with the major when removals land. Prefer adopting the replacement API during the window rather than waiting until removal day.
Ask in #ask-designsystem if a changelog entry is unclear about whether an API is deprecated or removed.

​
Beta (./beta) rules

Unstable surfaces ship under the @servicetitan/anvil2/beta subpath export (the package ./beta entry).
  • Patch-only changesets: every beta change uses a patch bump, including new beta features and breaking beta API changes.
  • Changelog: beta entries are prefixed with BETA so they stand out from stable notes.
  • Promoting out of beta: moving an API from @servicetitan/anvil2/beta into the stable package export is a breaking change for beta importers. Update imports to the stable path and treat the promotion as a migration, even when the API shape is unchanged.
  • Stable APIs are never broken in a patch. Only APIs explicitly marked beta may change incompatibly within a patch.
See Understanding Anvil2’s Beta Features for adoption guidance.

​
Maintenance lines and codemods

After a new major publishes to npm latest, older majors can keep receiving fixes on maintenance branches: Install a maintenance line with the matching dist-tag, for example:
For major-version migrations, use @servicetitan/anvil2-codemods when a transform exists for the change. Codemods reduce mechanical upgrade work; always re-run TypeScript and visual checks after transforming.

​
Communications

​
Per-release announcements

Every Anvil2 release triggers an announcement in #ask-designsystem so teams can track what changed and when.

​
Weekly changelog summary

A weekly batch summary of all Anvil2 package releases from the prior week is posted to #dev. This makes it easy for engineering teams to catch up on recent changes in one place.

​
Major release announcements

Major release announcements are shared approximately three months ahead of the target release window. Initial communication goes to the Platform team for coordination, then is shared broadly in #ask-designsystem and #dev.

​
Beta features

Some components and features are released as beta before being stabilized. Beta releases allow teams to try new features in real products and provide feedback while we continue to iterate. Semver and import-path rules for beta (patch-only changesets, BETA changelog prefix, and promoting out of @servicetitan/anvil2/beta) live under Beta (./beta) rules in the consumer compatibility policy above — keep that section as the single source of truth. Once a beta feature has enough production usage and feedback, it graduates to stable and follows standard semver guarantees from that point forward.

Understanding Anvil2's Beta Features

A deep dive into how beta features work, what the beta label means, and what to expect when adopting them.

​
Adopting Updates

To stay aligned with the system, teams should:
  • Review release notes when a new version is released
  • Integrate minor and patch updates promptly
  • Plan for major release migrations ahead of the release window
  • Remove deprecated usage as part of ongoing maintenance
  • Test UI behavior after upgrading the code package
  • Report issues or ask questions in #ask-designsystem

Changelog

Full history of Anvil2 package releases and changes.

Roadmap

See what the Anvil team is working on and what’s coming next.
Last modified on October 12, 2026