Versioning Strategy

#Background

Since the Fancy Design System team is small and is serving multiple product teams with multiple different tech stacks, it’s important for us to make maintenance of Fancy as lean and efficient as possible and the usage for product teams as convenient as possible.

Therefore we aim to use SemVer (Semantic Versioning) and only maintain a single version of FancyLib and are going for what we call a “Partial Migration” strategy. We go in-depth on this below, but it means we try to avoid a big bang release, and instead aim for partial migrations of new versions/updates to components.

This also means that if issues occur in components, the most typical solution will be to upgrade to the latest version.

#SemVer

We aim to use the SemVer standard for versioning. The format of the version number is MAJOR.MINOR.PATCH (eg. 1.3.1). Increment the:

1. MAJOR version when you make incompatible API changes (Breaking changes on existing components, deprecated components deleted, etc.)
2. MINOR version when you add functionality in a backward-compatible manner (New versions of existing components introduced with an alternative name, new components are introduced)
3. PATCH version when you make backward-compatible bug fixes (Eg. adding new non-required properties to existing components, fixing bugs that don’t require product teams to update code).

#How we plan to deal with breaking changes

It’s inevitable that we’ll make breaking changes to Lib components or create completely new and different components that should be used instead of existing Lib components.

We will handle these breaking changes by:

1. In a minor version of FancyLib, introducing a new version of the component with the name ComponentnameNew and placing it next to the old one.
2. Marking the existing component as deprecated (aka. marked for deletion).
3. Communicate the change in #dev_fancy with a set date for the grace period. Depending on the change, it will also be communicated in other relevant channels.
4. Introducing a grace period to replace the deprecated component with the new one. The size of the grace period depends on the size and scope of the updated version to be replaced.
5. After the end of the grace period, a major version will be released where we delete the deprecated component and rename ComponentnameNew to Componentname. At this point, every reference to ComponentnameNew needs to be updated to Componentname. For a while, in PFG, this will be handled by the Fancy team.

This way it’s possible to migrate while still on the old major version, without having to update major parts of your code in big-bang releases.

#Examples

#Scenario 1 - Design token update

We want to rename a design token $color—heat—1 to $color—scale—heat—1

• In a minor version of FancyLib, we introduce a new version called $color--scale--heat--1, next to the old one, and mark $color--heat--1 as “Deprecated”.
• Given the size of the update, this will be given a 30 day grace period, communicated in #dev_fancy
• In a future major version $color--heat--1 deleted.

#Scenario 2 - Component update

We want to add a new required aria-label to Dropdowns.

• In a minor version of FancyLib, we introduce a new version called DropdownNew, next to the old one, and mark Dropdown as “Deprecated”.
• Given the nature of this update, a developer might require input from either PO, UX writer, or Product Designer, therefore we will communicate the change to product teams / UX through relevant channels.
• Given the size of this update, this will be given a 60 day grace period, communicated in #dev_fancy.
• In a future major version Dropdown is deleted and DropdownNew is renamed to Dropdown.

#Scenario 3 - Pattern update

We want to change how Table works, so that now table filters are part of the table component, meaning multiple components are affected.

• In a minor version of FancyLib, we introduce a new version called TableNew, next to the old one, and mark Table as “Deprecated”.
• Given the potential impact on products or features, this will also be communicated at product sessions and the #product-owners slack channel and other relevant channels.
• Given the size of this update, this will be given a 90 day grace period, communicated in #dev_fancy.
• In a future major version Table is deleted and TableNew is renamed to Table. Documentation for Filters in TableToolbar is updated.