Releases & versioning
The Web Design System follows semantic versioning (semver) for all published packages. Given a version number x.y.z:
| Release type | Version bump | Example | When |
|---|---|---|---|
| Patch | z | 2.6.1 → 2.6.2 | Bug fixes and design corrections |
| Minor | y | 2.6.1 → 2.7.0 | New features or deprecations |
| Major | x | 2.6.1 → 3.0.0 | Breaking changes |
For packages that have not yet reached 1.0.0, breaking changes bump the y number (e.g. 0.2.1 → 0.3.0) and all other changes bump z.
Major releases can also contain new features, and any release can include bug fixes.
Release cadence
Section titled “Release cadence”We aim to release a new version of @volvo-cars/css every two weeks, but may release more frequently when needed. Other packages are released as changes are ready.
Our approach to breaking changes
Section titled “Our approach to breaking changes”Breaking changes cause interruptions and unplanned work for product teams, so we keep them to a minimum. We’d rather invest more effort to find a backward-compatible solution in one of our packages than defer the upgrade cost to every product team.
Whenever possible, we keep an older API working while adding deprecation warnings in preparation for future breaking changes. If your app doesn’t use any deprecated features in the latest minor release, it will be compatible with the next major release — allowing you to update your code gradually.
What counts as a breaking change?
Section titled “What counts as a breaking change?”The guiding principle: if a team can bump the version, release their application, and end users see no bugs — without any further code changes — then the change is not breaking.
API changes
Section titled “API changes”If bumping a minor or patch version requires any code changes beyond updating package.json and similar manifest files, the change is major.
Design updates
Section titled “Design updates”If the design system is updated, any deviation from it is considered a bug. A design or theme update in @volvo-cars/css is a patch release.
However, if a design change can affect layout or how a component interacts with its surroundings, it is breaking. For example: updating a color property can be done in a patch, but changing display from inline-block to block could require a major bump.
Component markup
Section titled “Component markup”The HTML structure of a component is not part of the public API. Avoid writing custom CSS that targets elements rendered by design system packages — the markup may change without notice. Changes to element types or nesting depth trigger a minor release but don’t need to be documented in release notes.
TypeScript changes
Section titled “TypeScript changes”If code that previously compiled without type errors no longer compiles after a package update, it’s a major release. Adding a @deprecated annotation may be done in a minor release.
Development warnings & deprecations
Section titled “Development warnings & deprecations”Since warnings and deprecations don’t affect production behaviour, they may be added or modified in minor releases. This is what allows us to reliably warn about upcoming breaking changes. New warnings are documented in changelogs.
Upgrading safely
Section titled “Upgrading safely”- Stay on the latest minor release. This ensures you see all deprecation warnings before the next major version.
- Enable linting rules. The
@volvo-cars/eslint-plugin-cssno-deprecated-classrule will flag deprecated classes in your codebase. - Read the changelog. Each release includes a changelog describing what changed. Pay attention to deprecation notices.
- Test visually. Use screenshot testing (e.g. Percy) when upgrading to catch unintended visual regressions.