Correcting document errors in semantic versioning

Question

Semantic versioning is a scheme of versioning that make the compatibility of different versions of a software component apparent to human and non-human agents.

In essence, when a backwards-compatible change is made (e.g. addition of features), minor version increases; bugfix results in patch version increase; and breaking change increases major version.

A semantic version of a software is bound to its API specification in order to maintain compatibility. But what if the software is correct while the (human-facing documentation) specification is in error? Does correcting a non-trivial error in the doc increase patch, minor, or major version?

Update

Per comment by @GregBurghardt, where the document is hosted is irrelevant for this Q, but it comes with the software distribution, and correspond to the version that it document, most importantly it defines the API (or ABI in some cases) of the software component.

Answer 1

Semantic Versioning is concerned with a public API. The first element of the specification says that the "API could be declared in the code itself or exist strictly in documentation".

If the documentation is the declaration of the API, then you need to think about the impact of this documentation error. The Semantic Versioning spec has guidance on what to do if you accidentally release a backward-incompatible change as a minor or patch version or if you inadvertently alter the public API.

However, if the documentation is not the declaration of the API, then Semantic Versioning is not concerned. When the documentation is not the declaration of the API, I'd consider this no different than the guidance for updating dependencies without changing the public API. If the documentation is bundled with a software release, it may be good to introduce a patch release to indicate that something has changed. However, if the documentation is outside the software package and release, then you can update the documentation without a change to the software.

Answer 2

Semantic versioning is not concerned with the documentation of a library. In this case, the API did not change at all. I did post some questions as a comment, which I think might be relevant, but here is how I would approach the problem:

• If this documentation is distributed with the library, then increment the patch version. Call it a "bug" in the documentation.

• If this documentation is deployed separately to a web server without being distributed with the library, I wouldn't even bother incrementing the version. Just package the new docs and deploy them. Don't fuss too much about this.

This is where something like Conventional Commits can give you a more expressive way to communicate what you are changing, and how it could change version numbers. Conventional commits and semantic versioning pare well together. The docs: commit message prefix is made specifically for this kind of case.

Overall, don't worry about this too much. If you have CI/CD tools that are only triggered by a version change, or you need to distribute the docs in the same archive as the library itself, increment the patch version. If this documentation is deployed separate from the library, don't feel like you need to change the version at all unless other tools require it.