Nowadays, versioning systems are used everywhere to simplify collaboration between developers working on the same codebase. That’s great, if it weren’t that, in the long run, commits history starts looking like this:
Has a commit introduced a breaking change? Any fix? Good luck finding the answer just looking at that: you’d better start walking in your open space asking who did what.
From this another problem arises. Let’s say you have to decide the software version number. Usually, it is composed by three numbers
X.Y.Z. How do you decide these values? And how do you create the changelog?
Let’s start by talking about Conventional Commits.
What’s Conventional Commits
Conventional Commits is nothing but a convention on how commit messages should be written. As stated by the official documentation, commits should be in the form:
<type>[optional scope]: <description> [optional body] [optional footer(s)]
And here a practical example, without optional fields:
feat: add new API to retrieve users
Main types could be:
feat, describing the introduction of a new feature
fix, describing a fix There are a bunch of them, you can find more information in the documentation.
Why it’s useful
Sometime a git log is worth a thousand words:
fix(lambda-article): change publish date fix(lambda-article): make article not draft anymore feat(lambda-article): add new article on lambda functions feat(cd): introduce github action to automatically build website
Just reading commit descriptions you can exactly understand what has been done. In this example, two features and two fixes were introduced.
You may say that you can do the same without using conventional commits. You’re right, so let’s talk about Semantic Versioning.
Semantic Versioning it’s a set of rules (or a framework) defining how to decide the version number.
Given a version
- X is the MAJOR: when introducing breaking changes
- Y is the MINOR: for new features
- Z is the PATCH: for new bug fixes
The link with Conventional Commits is obvious: from commits history you can exactly define the version number to assign.
Lot of tools can also autogenerate changelogs starting from commits history: here at Sky we use an internal one (what-bump, written in Rust), but there are a lot of open-source alternatives.
Just add these kind of tools in your release pipeline et voilà, version number set and changelog generated.