Semver for refactoring change

I have hesitated to ask this question, as it perhaps seems trivial and unimportant, but nevertheless it has been bugging me.

The question: what should you do when publishing a release that is neither a bug fix ( patch ) but does not have any new functionality either. For example, perhaps you just refactored some code, changed some private variable names, added some private internal documentation, or whatever. Nothing has been fixed, and no functionality has been added.


One option might be to not make a release at all, since it is only relevant for the author.


But if you do want to make a release, I'd definitely count this as a patch version bump only. You might say that it's an improvement, after all.


As refactoring may introduce unexpected change due to mistakes (possibly in combination with future changes of the language and/or or dependencies, which may behave differently even when exhibiting a behavior that's following their documented guarantees), I would recommend to always count refactoring as a "patch".

In the best case, behavior stays the same, but can you really always be sure?


An improvement seems more like a minor version than a patch. Ultimately, I think the answer is probably "it does not matter" (in most circumstances). But this is what is bugging me, you still have to make a choice and there is no clearly correct answer.

Bumping the patch number could suggest to clients that they need to upgrade to get a bug fix, when it is actually not necessary (and if there is a mistake in the refactoring they might regret it). I do think there are arguments both ways.

Minor versions are for backward-compatible new features. I don't think improvements count as such.


Agreed, but that is the dilemma. Bumping the patch is wrong, because there is no bug that was fixed, bumping the minor version is also wrong, because there is no backward incompatibility. So it is a question of which is the lesser evil.

I think it's wrong to assume that updates are mandatory, just because there is a new (patch) version available. If there is a critical bug, there should be an advisory and/or the old version could be yanked. Or do I misunderstand the yanking feature?


That is true, yanking is used to signal a bug, I had not considered that. That does seem to tip the balance towards using a patch version bump.

This can't possibly be the case by the definition of semver (I mean the "need to" part). This would make x.y.(z+1) backward-incompatible with x.y.z, so version resolution (in e.g. Cargo) wouldn't be allowed to select x.y.z instead of x.y.(z+1).

Hmm, I don't think I understand. What I mean is someone could use

cargo update --dry-run

and depending on what they see (with regard to patch version changes) decide to proceed with updating some or all of the dependency versions.

Given that the semver spec specifies that minor (and major) releases may also contain bug fixes, wouldn't someone that feels that they must update to the latest patch release for bug fixes also feel the same way about a minor release?


Semver has its philosophy, but a pragmatic approach to versioning is:

<upgrades may break API> . <downgrades may break API> . <fine either way>

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.