At PMC, we recently settled on a path forward for versioning our design system, Larva. It was in alpha for about 6 months longer than it needed it be, and completely skipped beta…I guess that has been one of the lower priority items to address, but I do feel like intentional versioning has the potential to be useful for us.
In our development workflow at PMC, versioning is not critical – most of our tech is built from the main branch and does not have versioning at all. In an ideal world, the design system would also follow this practice, and we would not release breaking changes. It makes the maintenance of many consuming projects much less time consuming, though it requires a trade-off of more risk and requiring more strategizing about how to release new features. In order to have this workflow for Larva’s npm packages, we will need to have automation that sets up the build in each consuming project, and reliable automated tests to ensure compatibility. Until that time – which may be pretty far into the future – we will need to explicitly version the npm packages, unlike the majority of our tech.
I proposed something that is essentially Semantic Versioning without the verbiage of breaking changes. The team gave it a thumbs up. Here is a blurb from our documentation.
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR when a widely used thing was deprecated, and code-bases need to be updated (e.g. deprecating the utility generator Sass mixins, updating the parser to use pmc-larva plugin) This does not mean a breaking change since we are not doing breaking changes.
- MINOR when there is an update developers should know about – a feature that can/should be used and is relevant to all code-bases (e.g. additions like utility classes, new tokens, array syntax support in the parser)
- PATCH when there is a bug-fix or other change that will not affect the workflow, and developers do not need to be aware of the details (e.g. adding a new brand to tokens, updating the UI in the pattern server, error handling).
So…why does this matter? Well, versioning is 1 of the 18,000 things you have think about when working on a software system of any kind. Even though it is a minor piece of the puzzle, it’s nonetheless a decision and therefore one less thing in the back of my mind. And, hey, maybe it will turn out to be useful in the long run…in theory, a version number can help communicate the health of a code-base, and developers can have language to refer to specific releases. Right?