Releases and versioning

VCC UI follows semantic versioning (semver) for the packages we publish. That means that with a version number x.y.z:

• When releasing bug fixes, we make a patch release by changing the z number (ex: 2.6.1 to 2.6.2).
• When releasing new features or deprecating existing features, we make a minor release by changing the y number (ex: 2.6.1 to 2.7.0).
• When releasing breaking changes, we make a major release by changing the x number (ex: 2.6.1 to 3.0.0).

For packages that have not yet reached 1.0.0, breaking changes update the y number (ex: 0.2.1 to 0.3.0), and all other changes update the z (ex: 0.2.1 to 0.2.2).

Major releases can also contain new features, and any release can include bug fixes.

Breaking changes

Breaking changes cause interuptions and unplanned extra work for product teams, so we try to keep them to a minimum. We'd rather spend more effort to figure out a backward compatible solution in a shared package than deferring the work of upgrading to all of the product teams. This means we publish most new features in minor releases.

Because vcc-ui is how we distribute updates to the design system and theme, we take extra care to minimize the effort required to upgrade to a new vcc-ui version.

Whenever possible, we'll keep an older API working but add add console warnings and TypeScript deprecations in preparation for future breaking changes. That way, if your app has no warnings on the latest release, it will be compatible with the next major release. This allows you to update your apps gradually.

What Counts as a Breaking Change?

If a team can bump the version of a package release their application to end users without causing anything an end user would consider a bug, and without doing any further code changes, a change is not breaking.

API changes

Bumping a minor or patch version in an application should never require any further code changes. If an API or export is changed in such a way that a team needs to update anything in their code base apart from package.json and similar manifest files, a change is considered breaking / major.

Development warnings and deprecations

Since these don’t affect production behaviour, we may add new warnings or modify existing warnings in minor version updates. This is what allows us to reliably warn about upcoming breaking changes. New warnings should be documented in the release notes.

Changes to component markup

The HTML structure of a component is not part of the public API, so you should avoid writing custom CSS targeting elements added by Web UI packages as it might change. Changes where element types or depth of nesting are changed should trigger a minor release but it does not have to be documented in the release notes.

Design updates

If the design system is updated, any deviation from it is considered a bug and a design or theme update in VCC UI is in itself considered a bug fix / patch release.

If a design change can cause issues with the layout or how the component interacts with other components on a page - it is a breaking change and triggers a major release. As an example: updating the color of a component can be done in a patch version, while updating the display property from inline-block to block could require a major version bump.

Design updates should be documented in release notes, preferably with screenshots. Screenshots can be added to Github release notes.

Even though simple color changes could potentially cause two components that were previously harmonized to now use different colors, it's preferable long-term the more components that follow the design system, even if a single page might not look ideal in the short-term, so there will be no opt-out alternatives to design system updates.

TypeScript changes

If code that previously compiled without type errors will no longer compile after a package update, it's a breaking change and requires a major release. Adding a @deprecated keyword only requires a minor version bump.