Semantic Versioning, and how to use bumpversion

What is a semantic version?

A semantic version comes in the form of a number, split into pieces by a . such as a.b.c, where:

  • a is the major version
  • b is the minor version
  • c is a patch

In a real scenario it would look something like:

  • 1.0.0
  • 1.0.4-snapshot
  • 0.1.7752
Photo by XPS on Unsplash

Some rules that tend to be followed when working with semantic versioning are:

  • Increase the Major version when the change is considered breaking, such as updating a contract of an API which would mean the consumer would have to recode the interface
  • Increase the Minor version when a change is made, which does not break the rule above, such as an improvement which does not require recoding of the interface
  • Increase the Patch version when working on bug fixes, or feature work which may still be under development.

Using Bumpversion to version a project

A small command line tool to simplify releasing software by updating all version strings in your source code by the correct increment. Also creates commits and tags

It really helps with managing semantic versioning, as it will automatically increase the version easily in different places.

I typically start with a basic bumpversion config similar to this:

[bumpversion]
commit = True
tag = True
current_version = 1.0.0

[bumpversion:file:setup.py]

[bumpversion:file:VERSION]

I then make sure to add in my setup.py and version to include this version:

./setup.py

import setuptools

with open("README.md", "r") as fh:
long_description = fh.read()


setuptools.setup(
name="my-project",
author="Craig Godden-Payne",
description="A utility that does something",
long_description=long_description,
long_description_content_type="text/markdown",
url="https://xxxxxxxxxxxxxxx.git",
packages=setuptools.find_packages(),
include_package_data=True,
python_requires='>=3.0',
test_suite='tests',
version='1.0.0'
)

./VERSION

1.0.0

Now every time I want to change the version, I just run the bumpversion command such as:

bumpversion patch - which will go from 1.0.0 -> 1.0.1
bumpversion minor - which will go from 1.0.0 -> 1.1.0
bumpversion major - which will go from 1.0.0 -> 2.0.0

Technologist who enjoys writing and working with software and infra. I write up all the things I learn as I go along to share the knowledge! beardy.digital

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store