What is a semantic version?

Software versioning has always been an issue ever since software has been created. Semantic versioning is a universal way of versioning some software or a development project where multiple versions of the software exist, or plan to exist.

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

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

bumpversion as described by its author is:

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