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. Examples:
  • large UI changes affecting multiple components
  • significant updates to foundational tokens
  • removing previously deprecated components or features
  • major changes to API or behavior
For major breaking changes, Anvil will provide teams with migration guidance at time of release. Teams should plan migrations as part of their sprint work and consult the DS team if they anticipate challenges. Consumers can view Anvil2 changelog here

​
Minor releases

Adds new features while maintaining backwards compatibility. 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. 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.

​
Communications

For every release type, the Anvil2 team publishes a release note that includes:
  • Categorization (major, minor, patch)
  • Package affected and latest version number
  • Author and PR number
  • Affected system elements
  • Migration guidance (when applicable)
  • Link to changelog
  • A support link
Release notes are shared in: Anvil pins the latest stable version in the monolith at code complete, allowing teams to test against it during regression testing. Release notes are shared with Release Management. Learn more about the Anvil communications schedule here.

​
Major Changes

For major breaking changes, Anvil follows the foundational change guidance for applicable updates, and coordinates all breaking changes with both the Release Manager and Platform teams. The goal is to ensure consuming teams have sufficient time to test and minimize impact on users.

​
Adopting Updates

To stay aligned with the system, teams should: -review release notes
  • Integrate minor and patch updates immediately
  • Plan for major release migrations
  • Remove deprecated usage as part of ongoing maintenance
  • Test UI behavior after upgrading the code package
  • Report issues or ask questions in #ask-designsystem
Last modified on January 28, 2026