What is the next version number if i do a refactoring or a documentation update only?

[christian-weiss]

My current version number is 1.2.3. Given i did a lot of refactoring (backward-compatible) and documentation updates since 1.2.3 (maybe 15 commits). All these commits goes into next build and therefor on success in the next release.
What is the next semver compatible version number?

As far a i understand:

1. Major version number remains unchanged, because there is no backward-incompatibility introduced.
2. Minor version number remains unchanged, because there is no new functionality added.
3. Patch version number remains unchanged, because there is no bug fixed.
4. Pre-Release string do not suite, because there is no new version number (see above).
5. Meta string is do not suite, because it is not took into account when precedence is calculated.

How to ensure that package is injected into project by dependency managers next time?

[FichteFoll]

You must at least increase the Patch version number for a new release.

Since you were refactoring, I'd say this counts as "bugfixes for bugs that didn't appear yet but could in the future". A kind of preventive bugfix. So, if you have no changes in functionality, I'd increase patch.

[christian-weiss]

The above question is rhetorical to illustrate the issue.

Spec §6 should be read as followes:

Patch version Z (x.y.Z | x > 0) MUST be incremented if you changed the package and your change is not introducing a backward incompatibility and not introducing substantial functionality or improvements.

[tbull]

Remember, you may increase ANY of the numbers ANY time, even without changes at all. That might not make sense most of the time, yet it is allowed. And it comes in handy in cases like this one.

Consequently, you have to choose which number to increase at your own discretion. You'd probably choose the number according to how extensive the rework has been. Trust your intuition! In your stated case I would tend to choose the Minor number. That also makes it easier for users to avoid this new version in case you have introduced new bugs by refactoring.

[FichteFoll]

That also makes it easier for users to avoid this new version in case you have introduced new bugs by refactoring.

That is a good point.

[christian-weiss]

Disagree. SemVer is all about semantic. And it works best, when all operators use a very similar increment pattern. Refactoring is about improving maintainability without changing functionality. If you do not trust your skills or your quality assurance process you do have a problem and semver is no valid solution for your problem.

Every commit has the potential to be in next release.
Every commit has the potential to introduce a bug or a backward-incompatibility.
Not every bug or backward-incompatibility can be discovered before software comes in production. Even if you do continuous improvement for years to improve your QA process.

When accept that fact your will discover that you need a strategy to handle bugs and bc issues when software is in production. A common understanding is, that providing a solution (bug fix, revoke a release) is time sensitive. Fastes known strategy to mitigate this is Continuous Delivery / Continuous Release which enables you to release within a very small timeframe (e.g. minutes). In continuous delivery, QA does not end before releasing. Production is in fact the last QA feedback loop.

I will choose "patch" for everything that do not break backward compatibility without introducing new functionality. And i hope this will be mainstream.

[rlidwka]

No bugs fixed, so it's not mandatory for users to update. Therefore it's minor.

[christian-weiss]

Good i have asked.

Following your logic:
No functionality introduced, so it's not mandatory for users (those who are looking for bugs and functionality only) to update. Therefore it's major.

Sounds like, we need a further version string element (z): w.x.y.z-pre+meta
To add semantic field for other changes. We should tread it as technical release (e.g. for continous integration).

Someone may want to classify "other changes" further into: refactoring, documentation update, legal update, tests added. Just to enable a more detailed version selection. Forcing next question, are these classes semantically on an equal level or do we have to sort that "flags" in a hierarchy to let the dependency resolver do its job.

At the moment there is no spec defined for a "version selection string". We need it. Maybe with a select a version range option and with an exclude option for specific versions or "flags".

[FichteFoll]

@christian-weiss Good idea, there is no negative match for metadata in the current spec of semsel besides regular expressions. Will add that. Related: #205

Edit: done

[openjck]

Related: #146

[FichteFoll]

Also related: #213

[jwdonahue]

@christian-weiss,

You must bump at least the patch level because you have made changes to the implementation of the API that can have an impact on end-user use cases. At the very least a refactor can change performance characteristics of the system just as much as a bug fix might do. Potential impacts on your user base are what determines which element of the triple gets bumped. Documentation updates should be considered as additional features, that may in fact introduce backward compatibility issues if they prescribe new restrictions on correct API usage (must call X before Y, for instance).

Version selectors should not be part of the SemVer spec as they would unnecessarily constrain tool designers. The stated precedence rules are all that are required for designers to chose selector semantics and syntax that meets their implementation needs. In fact, one implementation is the examples listed in #11 of the spec, which just uses the common less-than operator and the word 'equals' to specify precedence order. In any other language than English, this might more correctly be replaced with some other symbol(s) (however unlikely) that has the same meaning. In fact, a simple comma separated list can show the same ordering, or a columnar representation. Any range specifications can be easily built on top of less-than-or-equals semantics, in fact, only less-than or greater-than is required to specify a range.

[jwdonahue]

@christian-weiss, unless you have anything further to add, or intend to issue a PR against this issue, please close it at your earliest possible convenience.

[mjavadhpour]

Good article to handle refactor and release: Four strategies to version APIs and services

[jwdonahue]

@haacked, time to close this issue.

[filips123]

@jwdonahue How should version be updated if only documentation (or README file) is updated and code remains the same? Should MINOR or PATCH be updated? I think that PATCH should be updated because there are no functionality changes, but this also isn't a bug fix. Am I correct?

[steveklabnik]

@filips123 you should update at least the PATCH version. You're free to update MINOR if you wish, but that makes less sense to me, personally.

Given that there is an answer here, I'm going to close this. Thanks!

[christian-weiss]

Patch, Minor and even Major were suggested by commenters. And after seeing so many questions on the web about "what semver version should i use when doing refactoring or adding documentation?" in the last 4 years i think this issue still not well-addressed in semver - at least the patch, minor and major definition should provide better descriptions that also covers/includes refactoring and documentation.

No package-vender should be forced to anticipate what update strategy a package-consumer may have - because on a large community you can expect that nearly every possible update strategy will be used.
The package-vender should add semantic, not more and not less, but no anticipation.

If a refactoring do not reduce performance (increase of execution time) it should not considered as a new major release. As it also do not contain new features it should not considered as minor. As it is not a bug fix, just a change that improves maintainability, it should not be a patch release. Most package-consumer would be fine with not having a release at all, if it do not contain something that is important to API-consumers. Refactorings are for improving maintainability, so they are important for the package-vendor, but not (always) for package-consumer.

But if a package-vendor wants to enable technical-releases for a continuous integration server of a continuouse delivery pipeline (to test upstream integration) automatically to get a fast feedback loop then there is a need to bump the semver version number with semver 2.0.

Current semver 2.0 do not allow to add this semantic (for refactoring) and forces a package-vendor to anticipate the most used "update strategy" in his community and to bump a version accordingly. But then semver loses it unique selling point as it now not longer have a predictable semantic versioning "contract" between vendor and consumers - it may differ from package-vendor to package-vendor (and is often not explicit stated outside of semver at project-level) and the old guessing game from the early days before semver start again.

There is a good reason why "version selection string" (semsel) is not part of the semver spec. A vendor should not do an update strategy anticipation. He should focus on adding "fine-grained" semantic to his release. The rest is up to the dependency tool vendor and the package-consumer.

I think this issue is still valid and not yet resolved.

[christian-weiss]

steveklabnik please re-open this issue.

[jwdonahue]

The spec covers what it needs to cover, but perhaps the FAQ could use an update in this regard. Whether a refactoring is a major, minor or patch level change, really does depend on the product and its intended uses. A library of real-time signal processing routines might break customers if it speeds-up or slows-down execution due to a refactoring of its code, while a 1000% performance boost might just be all sweetness for a database query optimizer, but a 1% decrease could be a killer.

This should not have to be explained to real software engineers, and in any case, their customers are going to educate them either way.

I see no reason to revive this thread.