Releases

Release tags

In addition to the “Latest” tag, where the most recent stable release can be found, VA Clinical Design System packages containing “under development” code are at times made available under a few other tags to allow for experimentation and early testing.

A Canary release tag is used to make code changes available prior to release for testing purposes.

An Experimental tag may contain experimental features that extend the current base code and need to be made available.

Code under Canary and Experimental are not ready for production and should not be used in your production environment.

Canary tag

If you would like to experiment with the latest unreleased changes before an upcoming release, you may want to install the Canary release tag instead of Latest.

Please note that the Canary tag is not always up to date. Please refer to the tag name to identify which release is currently on Canary. For example 2.0.0-canary.10 means that this is the 10th iteration of the 2.0 release. If the release version in the Canary tag is lower than the current version, there may be little benefit in using the Canary tag as it is outdated.

You can find that information on the package page.

In order to do so, run the following:

npm install @department-of-veterans-affairs/clinical-design-system@canary

or

yarn add @department-of-veterans-affairs/clinical-design-system@canary

Experimental tag

If you would like to use experimental features that aren’t released yet, please use the Experimental tag as follows.

Again, refer to the tag name on the package page to identify which experimental feature is available under the tag.

Please note that some experimental tags might be outdated as they were released as part of previous versions.

npm install @department-of-veterans-affairs/clinical-design-system@experimental

or

yarn add @department-of-veterans-affairs/clinical-design-system@experimental

Cadence

We release every other week at the end of our sprint (on All Teams Sprint Demo weeks) on Monday.

Release notes

You can find our release notes on our repo located here.

Example of a breaking change called out in release notes:

Sem(antic) Ver(sioning) guidance

Versioning

As per semantic versioning guidance:

Breaking changes will be denoted by a change in the major version of the Clinical Design System
Non-breaking changes will be denoted by a change in the minor version of the Clinical Design System.
Non-breaking bug fixes will be denoted by a change in the patch version of the Clinical Design System.

General guidance

Unless otherwise noted below:

Breaking changes

• removing something from the design system (a token, a component, a functionality) will be considered a breaking change.

• changing something in a way that is not backwards-compatible (a token, a component, a functionality) will be considered a breaking change.

Non-breaking changes

• adding something to the design system (e.g. a new token, an new component, a new functionality, a new class, new aria-label) will not be considered a breaking change.

• changing something in a way that is backwards-compatible (a token, a component, a functionality) will not be considered a breaking change.

Important note:

The rules above (and below) only apply to tokens, components, and features marked as Ready for Production.

Components marked as Under Review or Work in Progress are considered volatile and may be changed without warning in any subsequent minor or major releases.

Further detail on specific categories of changes:

For further detail on how certain categories of changes will be interpreted by the Clinical Design System Team (as breaking or non-breaking changes) please see below.

Dependencies

Updating (or downgrading) dependencies will not per se be considered to be a breaking change. Instead, the team will consider the impact of the dev dependency on the application consuming the Design System to determine if a dependency update should be considered breaking or not.

Breaking changes:

• (Example) Updating a library dependency that dramatically changes the layout of a component

For these purposes, altering the layout or spacing by more than approximately 5% will be considered a breaking change. For instance, if a component has a padding of 100 pixels, a change of 4 pixels would be considered insignificant, while a change of 6 pixels would be considered substantial.

• (Example) Updating a library dependency that changes classnames or IDs

Non-breaking changes:

• (Example) Updating a library dependency that dramatically changes the box-shadow of a component

• (Example) Updating a library dependency that changes padding or spacing by a few pixels

Documentation Updates

Non-breaking changes:

All documentation-only changes will be considered non-breaking changes.

Deprecation

Non-breaking changes:

Marking a component, token functionality, etc as deprecated will not be considered a breaking change, as long as that item is not removed from the design system within the same release.

Breaking changes:

Removal of the item (even after deprecation) will be considered a breaking change.

Style changes

Breaking changes

• Major Layout Changes

  Example: layout of a component changes significantly

  For these purposes, altering the layout or spacing by more than approximately 5% will be considered a breaking change. For instance, if a component has a padding of 100 pixels, a change of 4 pixels would be considered insignificant, while a change of 6 pixels would be considered substantial.

Non-breaking changes:

• Changing a token value to a similar token value

  Example: changing the color $orange from one orange hex value to different orange hex value

• Minor Style Change: Example: padding changes by 2 pixels

  Note: this kind of change might cause a UI test to break, but will not be considered a breaking change as its impact to the consuming application is assumed to be negligible

• Minor Layout or Spacing Change

  For these purposes, altering the layout or spacing by more than approximately 5% will be considered a breaking change. For instance, if a component has a padding of 100 pixels, a change of 4 pixels would be considered insignificant, while a change of 6 pixels would be considered substantial.

Name changes

Breaking changes

All name changes will be considered breaking changes if that name is public-facing and consumable.

Examples:

• Exports
• Component Names
• Property Names
• Token Names
• Publicly Consumable Constants

Non-breaking changes

All name changes on code not considered to be public-facing or consumable will be considered to be non-breaking. If You have a question about whether a specific item is considered “public-facing” please ask in the public slack channel before building a reliance on it into your code.

Accessibility

Breaking changes

Examples:

• Requiring ARIA attributes where they weren’t needed before
• Changing keyboard navigation patterns

Non-breaking changes

• Any additive change that improves accessibility without breaking other existing functionality will not be considered a breaking change.

  Examples:

  • Adding an aria label
  • changing tab order to improve accessibility