Versioning Policy

1. Overview

• BAgel uses Semantic Versioning (SemVer) for its published npm package.
• The version number is expressed as: major.minor.patch (e.g. 3.85.0)

2. Scope of Versioning

Versioning applies to:

• BAgel Web Components (npm package)
• BAgel Helper
• CSS Utility Classes

Airframe updates are released in tandem when possible, but are versioned separately.

Styling, internal component structure, and non-public implementation details are not covered by SemVer guarantees.

3. Semantic Versioning Rules

3.1 Patch Releases (x.y.Z)

Patch releases do not add or remove public API.

Patch releases include:

• Bug fixes
• Colour adjustments
• Non-breaking visual refinements
• Non-breaking behavioural changes
• Internal performance improvements to components

3.2 Minor Releases (x.Y.z)

Minor releases add new functionality in a backwards-compatible manner.

Minor releases include:

• New components
• New props, attributes, or slots
• New non-breaking features
• Additions to existing component behaviour
• Introduction of aliases for renamed props, components, or utility classes

3.3 Major Releases (X.y.z)

Major releases are rare, and the team works to avoid them whenever possible. When they are necessary, they are communicated well in advance with clear migration paths.

Major releases are reserved for changes that break the public API, including:

• Removal of deprecated components
• Removal of deprecated props/attributes
• Renaming or removing public props/attributes without an alias
• Deletion or renaming of components where an alias cannot be maintained
• Changes to slot names
• Changes to CSS utility class names
• Changes to component names

4. Public API Definition

The following elements are considered public API and are covered by SemVer guarantees:

• Component names
• Props and attributes
• Slot names
• CSS utility classes

Not Public API

The following may change at any time without a major release:

• Internal markup structure / DOM shape
• CSS custom property names
• Shadow DOM structure
• Implementation details of styles

Consumers must not rely on internal DOM structure for automated tests. Props and attributes should be used instead.

5. Deprecation Policy

5.1 Deprecation Strategy

Deprecation timelines vary depending on component usage and impact. The Design System team evaluates each deprecation on a case-by-case basis.

The Design System team aims to provide adequate time for teams to migrate, balancing stability with forward progress.

5.2 Communication Channels

Deprecations are communicated through:

• Documentation site (labels, banners, migration notes)
• BAgel Helper (console warnings)
• GitHub changelog
• Teams and Slack channel announcements

5.3 Compatibility During Deprecation

• Older versions are not supported.
• No long-term support (LTS) is provided.
• Deprecated features are removed in the next major version.

During a deprecation period:

• Deprecated APIs remain available until the next major release
• Aliases for renamed props, utility classes, and components are provided
• Deprecated and new APIs may temporarily coexist during migration periods

6. Experimental Features

• BAgel does not publish experimental or unstable components.
• All published components are stable and part of the public API.

7. Release Cadence

• BAgel releases updates as needed, not on a fixed schedule.
• Airframe updates often accompany code updates but do not enforce version bumps.

8. Governance

• The Design System team maintains full ownership of the system.
• New components and major changes go through an RFC process, available on request.
• Breaking changes require internal approval and must be documented clearly.

9. Communication Expectations

Every release includes:

• A GitHub changelog entry
• Documentation updates

Minor releases include:

• Announcements in the Teams and Slack channels with a list of patch releases between minor releases

Major releases also include:

• An upgrade guide
• Announcements in the Teams and Slack channels
• Direct communication to key stakeholders