During the last year I've become more involved in building the design system we use at Signavio. While doing so rolling out changes to the company turned out to be a major challenge. We had been doing it for some time but we somehow managed to get certain parts wrong all the time. Sometimes we released breaking changes with minor updates or forgot to write proper release notes. A developer who did not contribute to the design system on a regular basis could make mistakes way too easy. Initially, we thought that what we were missing was proper documentation but it turned out no one reads the docs anyway.
When we rebooted the design system I took it upon myself to try to solve at least some of these issues.
We had been using a tool called
sematic-release on another project already (so I had at least some experience) and decided to use it here as well.
I made a small list of requirements that I would like the solution to support.
- force developers to think about the implications of their work while they were doing it
- automate most of the process to remove the possibility of human error
- be nice enough that even managers see the value
A version number follows the
If you increase the
patch number you've, for instance, fixed a bug.
You definitively have not added some new functionality.
Because then you would have increased the
Generally speaking increases to the
minor numbers represent non-breaking changes.
This is helpful to determine whether your software is compatible with an update.
Let's say you're running on version
1.0.2 and there is an update incoming with the version
As this means that the changes are either new functionality or bug fixes, you can upgrade without breaking your existing code.
This isn't the case when the
major version increases.
If this happens it indicates a breaking change.
The biggest question you now have to answer is "What is the breaking change?" and "Does it affect me?".
We see that the version number plays an important role in figuring out whether an update is safe or not. If we want to know what changed then the version number isn't enough. We need to see a changelog or release notes.
If we assume that developers understand what they're doing while they are doing it we can leverage this fact.
semantic-release creates release notes based on the commit history of a repository.
In order for this to work developers need to adhere to a format called semantic commit messages.
A regular commit includes information about what has changed.
A semantic commit also adds context to that information.
For instance the commit message
button did not accept onClick handler
fix: button did not accept onClick handler
This is a small change but now
semantic-release is able to figure out that this commit contains a bug fix and can use the commit message as the description for what the developer fixed.
Admittedly, this requires some effort by developers but tools like
commitizen help to make the transition less painful.
We also introduced
husky so that there is a precommit hook that makes sure every commit follows this pattern.