A brief guide to Semantic Versioning
Whenever releasing a product or app, you’ll want to version it. This helps users understand what stage the app is at and also helps when integrating the app into package managers. In Software Development, we version apps by following Semantic Versioning, which is a general template that everyone uses and understands.
Why bother?
Versioning our apps helps us keep track of what’s been added/removed at what point. It can get real hectic, real fast, especially in the early stages when you’re releasing new features and fixing bugs. You’re gonna want to reference things that have been added or things that have been fixed.
Where would I keep a track of this?
You can tag your releases on Github using git tag. Essentially, you just tag a version number to a specific commit, like a merge, push it and this appears on the repository under “releases”, with any notes you’d like to add. It’s best to keep track of all these changes in a CHANGELOG, there’s a nice format to follow outlined here. This way you can keep track of what’s been fixed and any upcoming features that are being released into the next version. It’s also important to remember, software is built for people. So people need to actually understand what’s going on and at what stage your apps currently at, having a well documented CHANGELOG helps provide a clear timeline and explanation of your app.
Ok, so how do I go about versioning my app/package?
0 — Pre-MVP/Alpha
At this stage, you’re developing your app and still building towards an MVP. There’s no real point differentating between versions here because it’s not a useable product yet. During this period, the version will remain at 0.
Major.Minor.Patch — Alpha/Beta
Once you reach your MVP, you might iterate over this and create Alpha/Beta releases for users to test and supply feedback on. When creating your first release, you’ll want to start versioning. This helps you keep track of your app and creates a timeline of what features were added when and what bugs have and have not been fixed yet. You might be wondering, what exactly constitutes a major, minor or patch release.
Major Release — Increment the first digit by 1 if the new features break backwards compatibility/current features
Minor Release — Increment the middle digit by 1 if the new features don’t break any existing features and are compatible with the app in it’s current state.
Patch Release — Increment the last digit by 1 if you’re publishing bug/patch fixes to your app.
Before publishing your first, useable version, you might find yourself incrementing the middle and the last digit to keep track of Alpha/Beta releases. Only once you’re ready for a proper, first release, should you start versioning from 1.0.0.
I can’t stress enough the benefits of keeping a clean, well documented CHANGELOG. Regardless of whether your project is open source or not, it’s vital to keep track of what’s been worked on. It helps guide you when deciding what features need work and gives you good insight into your release cycle.
If you’re interested in reading more, you can get the full breakdown of Semantic Versioning on their site.
As always, thanks for reading, hit 👏 if you like what you read and be sure to follow to keep up to date with future posts.
