"What Version Are You On?"
When you first start a project, "versioning" just means the latest commit on the `main` branch. But as soon as other people (or other services) start using your code, that’s not good enough. If you release a new version that breaks their application, you’ve created a serious problem. This is where Semantic Versioning (SemVer) and Git tags come in, providing a clear, universal language for software releases.
What is Semantic Versioning?
Semantic Versioning is a simple set of rules and requirements that dictate how version numbers are assigned and incremented. The format is always MAJOR.MINOR.PATCH (e.g., v1.4.2).
- MAJOR (
1.4.2): You increment the MAJOR version when you make incompatible API changes (i.e., a breaking change). - MINOR (1.
4.2): You increment the MINOR version when you add functionality in a backward-compatible manner (i.e., a new feature). - PATCH (1.4.
2): You increment the PATCH version when you make backward-compatible bug fixes (i.e., a bug fix).
By following this standard, you are making a promise to your users. If they are on version v1.4.2, they know they can safely upgrade to v1.4.3 or even v1.5.0 without their code breaking. But an upgrade to v2.0.0 will require them to read the release notes and adapt to breaking changes.
How to Create Releases with Git Tags
A Git tag is a way to mark a specific point in your repository’s history as important, typically to mark a release. Unlike a branch, a tag is a fixed pointer to a single commit.
There are two types of tags, but you should almost always use annotated tags because they are stored as full objects in the Git database and can include a message, author, and date.
Here’s the workflow for releasing version v1.1.0 of your project:
# 1. Make sure your main branch is clean and up-to-date
git checkout main
git pull origin main
# 2. Create an annotated tag for the new version
# The -a flag makes it annotated, -m provides the message
git tag -a v1.1.0 -m "Release version 1.1.0: Add user profile avatars"
# 3. Push the tag to your remote repository
# By default, `git push` does not push tags. You must do it explicitly.
git push origin v1.1.0
Alternatively, to push all your local tags at once, you can run git push --tags.
Managing Your Tags
Here are a few other useful tag-related commands:
# List all existing tags
git tag
# Show information about a specific tag
git show v1.1.0
# Delete a local tag
git tag -d v1.0.0
# Delete a remote tag (a bit of a weird syntax)
git push origin --delete v1.0.0
Using SemVer and Git tags elevates your project from a simple repository to a professional software package. It builds trust with your users and provides a clear, predictable roadmap for your project’s evolution. It’s a fundamental practice for anyone who builds software that others rely on.