Semantic versioning: Am I allowed to move git tags to a different commit?

Question

Let's say I tagged commit A of my library with tag v1.0.0.

Now, I make a minor fix in the API documentation, let's say, fixing a typo. I commit this change, so new commit B now comes right after A .

Am I allowed to move the v1.0.0 tag to commit B , since I didn't make any breaking changes, and the code of my library is exactly the same as in commit A ?

Or, do I need to include even such small changes in a follow-up patch , eg v1.0.1 instead?

Answer 1

Point 3 in SemVer 2.0 makes this pretty explicit:

Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.

Note that SemVer has no regards for your source code management tools, only the released package . If the released package has changed, then it is a new version. So, if your documentation ships as part of the released package, fixing it is a change to the package.

On a practical note, as soon as you have shared a tag, or a labelled release, people who have downloaded that release may make explicit assumptions, such as that a SHA hash of its contents will match each time they download it, or that a mirror of your git repository won't have to overwrite already-fetched tags.

Generally, SemVer treats version numbers as "cheap" - keeping things consistent and predictable is more important than any emotional attachment you might have to low numbers, and a version number like "54.23.13" is perfectly fine.