Leveraging Semantic Versioning for Shared Libraries at TourRadar
At TourRadar we are convinced that a microservice architecture is a key enabler for agile and innovative teams. Instead of building a big monolithic beast, we are striving for multiple small maintainable codebases, both on the backend and frontend. But this is not a holy grail with only advantages. There are also challenges.
In this article, we are going to talk about the principle of semantic versioning in the context of shared component libraries for our single page applications, but it can be applied to any codebase.
Why we need semantic versioning
Let’s take as an example a set of components (in the following called ACLib) which is used in Application X. You are very happy about the functionality and after some time you copy ACLib into Application Y and Application Z codebases. Everything is fine until someone finds a bug in your shared library. You now have to update all occurrences in all codebases.
This approach is clearly violating the DRY principle. Instead of copying, we can include the same ACLib in all three different applications. However, changing the library’s code in order to enable a feature in Application X could very well lead to breaking the other applications that depend on it. The solution to this problem is introducing versioning for ACLib. Each application can then decide which version of the library it wants to use.
What Needs Versioning?
Having established the benefits of versioning, let’s have a quick look into what kinds of code changes we can have in our code base:
- Bug fixes
- Build config changes
- Documentation updates
- Performance fixes
- New features
If we try to group them we could come up with 4 different categories, namely:
- Breaking changes
- Features
- Fixes
- Others
If we leave Others out of this equation, we end up with 3 categories of code changes. We start by giving each category an individual count and increment it by 1 as soon as a code change for that category happens. For improved readability, we put dots in between and start with 1.0.0.
Let’s say we introduce a new feature: the version would change to 1.1.0. After that, we introduce a breaking change. The next version string would then be 2.0.0. This is an important rule: every time a number for a category changes, all counts to its right are reset to 0. This is exactly what semantic versioning is all about (for further information see https://semver.org/).
How Do I Get Semantic Versioning?
At TourRadar, we love automation. Every manual step that can be automated saves precious time for our developers. The semantic versioning process and releasing code is no exception.
The whole concept is based on properly formatted commit messages. There are various conventions how git commit messages can be formatted, but we decided to stick to the default and use the preset the Angular folks came up with. This follows a simple grammar:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>One can identify three parts of the message: the header, which consists of type, scope and subject, the body and the footer. The only mandatory part is the header, which should contain type and subject.
Based on the type of each commit message, our automated tool is capable of deciding which version bump is necessary for the next release. For example, if we are currently in version 3.4.2 and the scripts encounters three commits including two bug fixes (type would be fix) and one new feature (type would be feat), the next version would automatically be 3.5.0.
A real world example would be the following:
fix(key-inject): Remove key-inject command as we are going to face a hen-egg problem.BREAKING CHANGE: key-inject command won’t be supported by tr-react-scripts anymore.
This highlights the way to communicate breaking changes. Although the commit was a fix, due to the keyword BREAKING CHANGE being used, the first digit of the version string is increased. For instance, 3.5.0 would become 4.0.0.
What’s in It for Me?
You may question yourself what you get for the extra hurdle in formatting your commit messages in a predefined way. With semantic-release, the possibilities are endless as you could write your own plugins and embed them into the release flow. This provides us with some gems:
- Git tags which are set on each release commit
- Automated publishing to our private npm repository
- CHANGELOG.md for free
Did we mention we love automation?
For now, we are following the described workflow only in our shared JavaScript libraries that are used within other projects. Nevertheless, we are discussing whether following this approach throughout all projects at TourRadar could make it easier for new employees to get started and get each developer in the mindset of improving git commit messages quality.
Interested in joining TourRadar and helping provide life-enriching travel experiences? We’re always looking for talented and passionate individuals to join our engineering team!
