skip to content
f1sh
ci

Semantic Release - versioning made easy

/ 3 min read

tl;dr

By way of adhering to a commit message format, you’re delegating the versioning tasks to your commits with Semantic Release. And yes it has a python implementation.

In a nutshell

Semantic Release facilitates the versioning of your project based on your commit messages as it analyzes them for keywords simply put.

For example, commits are to follow the format: <type>[optional scope]: <description> where <type> must be one of the following according to the docs:

  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • ci: Changes to our CI configuration files and scripts (examples: CircleCi, SauceLabs)
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • test: Adding missing tests or correcting existing tests

<scope> pertains to:

The scope should be the name of the npm package affected (as perceived by the person reading the changelog generated from commit messages).

<short summary> is advised to be in present tense, not capitalized and without period at the end.

To bump or not to bump

Having our commit messages follow a convention as prescribed by Angular Commit Guidelines, automations are made possible. Indeed, Semantic Release affords us an automated way to version our projects by looking at the commit messages.

It looks at the intent of the commits by reading the type. For example, if it a fix commit, we bump PATCH version. Otherwise, if it’s a BREAKING CHANGE, we bump the MAJOR version.

Common Workflow

In our case, we want Semantic Release to be part of our CI/CD pipeline. We looked for a Python implementation for our python project and used the Github Action sample workflow and worked our way up from there.

The workflow looks like this:

  1. Developer commits fix: handle null cases
  2. Developer pushes to relevant branch where the Github Actions will run Semantic Release
  3. A PATCH bump is created and committed to the project
  4. The commit is then version tagged and a release is made in Github Releases pages
  5. As a bonus, the release page contains the changelog of all the commits in the release

How about configurations?

You can customize your Semantic Release by adding a section to your pyproject.toml. Among others, you can specify whether you want to publish to PyPI and Github Releases. See Configurations for more.

Conclusion

As much as it is critical, versioning is unfortunately mundane and prone to error. We craft our own ways to automate it but not fully. I find Semantic Release friendly to get started with and once it’s up and running, we just need to be mindful of how we write our commit messages.