mirror of
https://github.com/semver/semver.git
synced 2026-07-11 03:53:53 -05:00
[GH-ISSUE #215] What is the next version number if i do a refactoring or a documentation update only? #6134
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#6134
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @christian-weiss on GitHub (Aug 23, 2014).
Original GitHub issue: https://github.com/semver/semver/issues/215
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:
How to ensure that package is injected into project by dependency managers next time?
@FichteFoll commented on GitHub (Aug 23, 2014):
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 commented on GitHub (Aug 23, 2014):
The above question is rhetorical to illustrate the issue.
Spec §6 should be read as followes:
@tbull commented on GitHub (Aug 23, 2014):
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 commented on GitHub (Aug 23, 2014):
That is a good point.
@christian-weiss commented on GitHub (Aug 24, 2014):
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 commented on GitHub (Aug 26, 2014):
No bugs fixed, so it's not mandatory for users to update. Therefore it's minor.
@christian-weiss commented on GitHub (Aug 26, 2014):
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 commented on GitHub (Aug 26, 2014):
@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 commented on GitHub (Jan 12, 2015):
Related: #146
@FichteFoll commented on GitHub (Jan 12, 2015):
Also related: #213
@jwdonahue commented on GitHub (Dec 7, 2017):
@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 commented on GitHub (Dec 7, 2017):
@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 commented on GitHub (Jan 4, 2018):
Good article to handle refactor and release: Four strategies to version APIs and services
@jwdonahue commented on GitHub (Jul 15, 2018):
@Haacked, time to close this issue.
@filips123 commented on GitHub (Jan 25, 2019):
@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 commented on GitHub (Feb 11, 2019):
@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 commented on GitHub (Feb 16, 2019):
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 commented on GitHub (Feb 16, 2019):
steveklabnik please re-open this issue.
@jwdonahue commented on GitHub (Feb 19, 2019):
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.
@nsajko commented on GitHub (Mar 1, 2025):
Then what is Semver for?
@jwdonahue commented on GitHub (Mar 2, 2025):
@nsajko, see the intro section of the spec.. If you have further questions on the matter, that are not relevant to the OP's central question(s), please start another thread.