Semantic versioning on a dev dependencies change

Question

There are a few threads about how to handle the version number with semver upon changes in dependencies (usually resulting in a +1 to the patch number). Mine is probably a corner case: what if you are just updating a development dependency (e.g., a linter, a test library, a formatter...)?

Usually, from the user perspective nothing changes. Sometimes, nothing changes into the business code at all! However, you are formally in front of a potentially different codebase which relies on a different dependency set. Should I bump my library from, say, 1.0.0 to 1.0.1, or should I stick to the current version number?

Example 1 (Python) Bumped black (formatter), pytest (testing library), and mypy (linter). New versions do not change the business code.

Example 2 (Python) Bumped pytest (testing library) and refactored some tests thanx to the new pytest API. Again, no actual changes to the business code.

Answer 1

Based on the Semantic Versioning specification, any changes to a versioned package must result in the release of a new version of the package.

If the development dependency is not part of the versioned package, then you don't need to do anything with the version. You could optionally use the build metadata portion to identify the changes to other parts of the versioned package, such as the development dependencies.

However, if the development dependency is part of the versioned package, then you would need to increment the version. The major and minor versions are both defined with changes to the public API. Since a development dependency update, by itself, doesn't change the API, these aren't appropriate. This leaves the patch version.

The patch version is described as incrementing "if only backwards compatible bug fixes are introduced" and a bug fix is defined as "an internal change that fixes incorrect behavior". Although updating a development dependency is not a fix for incorrect behavior, it's the only available option.

It is possible to make an argument that you should be using the build metadata component. However, build metadata does not factor into precedence for versions. That means that if you have a version 1.0.1+25072022 and a 1.0.1+26072022 where 1.0.1+26072022 has updated development dependencies, you cannot assert an ordering of these two builds. You probably want to be able to assert that your latest development tools are the preferred version to use going forward.

Although it's not fully consistent with the Semantic Versioning specification, my recommendation would be to increment the patch version.

Answer 2

If the change in development dependencies is not part of a larger change in the API or internals, don't even increment the version number. This would be considered "work in progress", not a release. Document this in a commit message and a "ReadMe" file.

Semantic versioning does not cover a use case like this, because there is no change to the API. If this change in development dependencies is tied to other API changes, then increment the version number according to changes from the perspective of the consumers of your API, not the people building the API.

Answer 3

Adding to Greg's answer:

If the change in development dependencies does not affect the consumer of your library, then you should not release a new version at all.

Simply make the change on your development branch and include it in the next release that affects the users.

If your goal is to rewrite large parts of the library, you might consider releasing a version anyways to ensure that new bug reports still apply. In that case you can simply increment the patch version.