Intelligence Community Design System

This page provides details on how the@ukic/ packages and website are released and versioned.

Releases are triggered once thedevelop branch pull request is merged into themain branch. The package versions follow the semantic versioning scheme.

Major releases contain breaking changes to the component libraries. Breaking changes are communicated to the community as early as possible to allow teams to plan when to integrate the new packages into their projects. Major releases are very infrequent, with at least a year between them.

Minor releases contain new component features. Minor releases are backwards-compatible with no requirement for the developer to make updates to their existing implementation. However, to use the new feature, the implementation will require a small update (such as adding a new prop) in order to use the new component application programming interface (API).

Patch releases contain bug fixes.

Minor and/or patch releases are scheduled every two weeks. All changes to the component library are recorded in the Web Components CHANGELOG.md .

All packages are published with identical version numbers.

Beta components are an intermediate stage in our versioning system, between the initial "Alpha" testing phase (peer review) and the stable release.

When a component reaches the Beta stage, it has passed the preliminary phase but is not yet deemed fully stable. This allows us to release components for wider testing and gather feedback from our user community while further fine-tuning their functionalities and addressing potential issues.

Beta components are integrated into our normal@ukic/ packages and can be installed just like any other stable component. They are easily accessible to developers and users who wish to explore the latest developments and contribute to the improvements.

It is important to be aware of a few points when working with Beta components:

We consider Beta components acceptable for use in production-ready applications, as long as customers are happy with the issues mentioned previously.

We regularly review the stability and reliability of Beta components. When the component meets the criteria it can be transitioned to a stable release.

Canary components are unstable components that are released for testing purposes.

These components should not be used in production apps without understanding the risk that changes may occur in order to fix bugs or improve functionality.

We consider a canary component to be acceptable for moving to Beta once customers have tested its usage and provided enough feedback to suggest they're happy with it.

Canary components can be installed in the same way as our core@ukic/ packages, but prefixed with canary, for example@ukic/canary-react or@ukic/canary-web-components .

A difference between our canary packages and our core@ukic/ packages is that canary package versions follow a<version>-canary.<build-number> pattern.

Another difference is that docs for canary components won't appear in the Components guidance section of this site. Instead, docs can be viewed in our Storybook instance for either React or web components .

As the component library matures and new versions arrive, the ICDS team will actively maintain and support the previous major version for up to 6 months. This is to allow the team to provide as much resource as possible on the current version. Any support for the legacy versions will only include security updates and bug fixes. No new features will be added.