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
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
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
Patch releases may also include breaking changes to beta features. See Beta features below.
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.What to expect from beta
- Beta features may change, including breaking API changes, within patch releases.
- Beta features are clearly marked in the changelog (prefixed with BETA) and in documentation.
- Stable APIs are never broken in patch releases — only APIs explicitly marked as beta may change incompatibly.
When beta features graduate
Once a beta feature has enough production usage and feedback, it will be stabilized and follow 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