SEMV is a read-only semantic version commit parsing and validation tool. It is intended to help with automatic versioning following a semantic version logic.
This package is inspired by a talk by Stephan Bönnemann as well as the package python semantic release. Both suggest parsing commit message to automatically create a new version number. Although this is a great idea, I don't think that commit messages can be guaranteed to be of sufficiently high quality to be used for this. Stephan's talk acknowledges this point and suggests strategies for automatically validating commit messages.
Unfortunately, these are not implemented in python semantic release. In addition, python semantic release does a lot more than just versioning: It covers the full release process, including uploads to pypi or github releases. As a result, running python semantic release can have quite a few unexpected side effects that might be difficult to undo.
I would prefer a tool that does the hard part of the automatic semantic versioning (parsing and validating commit messages) but doesn't have any side effects—the user should be free to use tags, variables, commits or whatever they like to represent new versions and the user should not be surprised by unexpected write operations. I therefore wrote semv, a read-only semantic version commit parsing and validation tool.
Installation and usage
You can install semv from pypi using
$ pip install semv
If you are inside a git repository, you can use semv to print the semantic version that the current commit should receive. E.g.
$ semv v1.0.5 (no-eol)
Here, and anywhere else in this documentation, the
$-sign indicates an interactive command line prompt and doesn't need to be typed.
(no-eol) tag will not be shown and is only intended to indicate that semv will not print a newline character. That means that you could use semv to create a version tag like this:
$ git tag $(semv)
Note that semv itself will have not change anything about your repository. It is up to you to use the printed version. An example for using the printed version is given in semv's own release workflow.
Other usage patterns can be found in alternative usage,
for example using semv as a
commit-msg hook to check commits before
committing them to version control.
Understanding semantic versions
Semantic versions are version numbers that carry some basic information about the content of the corresponding release. Semv aims to help with automatically creating releases that have semantic versions. Specifically, semv will create the main segment of a semantic version identifier: vX.Y.Z, where X is usually referred to as the "major" version, Y is usually referred to as the "minor" version and Z is usually referred to as the "patch" version. We will stick to these names throughout this documentation because they are quite common.
Having three separate version numbers isn't in itself necessarily useful. However, in semantic versioning, these three separate numbers indicate different kinds of releases:
- A major release (i.e. one that increments the X component of the above version numbers) is a release that breaks previously existing functionality. In fact, this could be something as simple as removing a feature, but often it will rather be a change in the software's user interface.
- A minor release adds functionality. Typically, that would be a release that implements one or more new features.
- Finally, a patch release would not change functionality but includes an improvement in existing functionality. That would typically be bug-fixes and performance improvements.
Semantic versions are useful for consumers of a package: They can often specify a range of versions e.g. ">=v1.3.0" and "<v3.0.0" to indicate that they rely on a feature that was implemented in version v1.3.0 but they can't work with a functionality or interface that was removed in version v3.0.0. Note that this also signifies that they can live with the breaking change that was introduced in v2.0.0.
Python's semantic versioning strategy further allows for qualifiers after the core version identifier that mark things like post-releases or release candidates. See pep 440 for detail.
In order to automatically calculate the next version, semv parses commit
messages (and potentially performs additional steps). That means that commit
messages should be formatted in a particular way: Each
commit message should start with a line of the form
type would be a commit type like "feat" or "fix" and
"scope" would be the thing that was actually changed. For example, the commit
message "feat(parsing): Parsing can now handle foo as well" would describe a
commit that adds a new feature to the parsing component of your application.
Starting with version v2.4.0, semv will use the scope for the new changelog
Below the first line, users can add a body (as is good practice with commit
messages in general). The body should be separated from the title by an empty
line. In order to detect breaking changes, semv will expect the body to start
BREAKING CHANGE: if the commit contains a breaking change.
In addition to commit parsing, semv can be configured to also run additional checks to—for example—detect some forms of breaking changes automatically.
In general, semv should have reasonable defaults. However, you can configure
semv via the
pyproject.toml config file. Details of the configuration
options are here.