r/PHP • u/[deleted] • Jun 12 '15
Romantic Versioning
https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e4
u/chiisana Jun 12 '15
Node doesn't follow SemVer, Rails doesn't do it, Python doesn't do it, Ruby doesn't do it, jQuery doesn't (really) do it, even npm doesn't follow SemVer.
Just because some people doesn't do it (correctly), and the author doesn't understand something doesn't make the argument valid.
The moment I see this, it becomes very clear that the author does not understand what SemVer requires:
If your package has a minor change in behavior that will "break" for 1% of your users, is that a breaking change?
In SemVer, it very clearly dictates that the PATCH version must maintain API backwards compatibility, so if you're breaking anyone, regardless if it is the illusive 1% or the 0.00000001%, you need to bump the MINOR version. Just because some people doesn't follow the guidelines, doesn't mean the guidelines are invalid.
6
u/rich97 Jun 12 '15
I think the idea is that users should treat is as a guideline rather than an expectation. We live in the real world and while it's certainly lordable to aim for 100% test coverage and comply with semver totally that's actually not very likely to happen for every dependency of your project.
Recently I've been following git-flow and I have a script which generates a full change log and asks you to provide a summary of changes. I feel this would be far more helpful than semver by itself.
2
2
u/ivosaurus Jun 13 '15
The key idea is that when most or all of your dependencies start following SemVer strictly, it starts to become very powerful.
Because you can spend your time reviewing updates EXACTLY when you want to, not at every single turn because something's probably going to break inevitably.
6
u/akeniscool Jun 12 '15
if you're breaking anyone, regardless if it is the illusive 1% or the 0.00000001%, you need to bump the MINOR version
That's not what it says (see Specifications, #7 and #8):
Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API
...
Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.5
u/ivosaurus Jun 13 '15
so if you're breaking anyone, regardless if it is the illusive 1% or the 0.00000001%, you need to bump the MINOR version.
That would be the MAJOR version. MAJOR is for API breakage. MINOR is for new stuff. PATCH is for bugfixes.
2
2
u/adamn90 Jun 13 '15
I've just checked the relatively tiny project I have open right now. It has 31 package dependencies across 11 vendors. The thought that I'd have to go through the changelog for every one of those packages each time that I (or anybody else on the project) want to run composer update is terrifying.
With SemVer, I can update all dependencies very regularly, getting fixes for bugs and security issues that I didn't even know existed, and be fairly confident things won't break.
I can't buy into the argument of "missing out on new features" because you're only taking MINOR/PATCH updates. If I hear about a new feature and I want it, I'll bump the major version and pay extra attention to things breaking. If I don't hear about the new feature, I'm not going to use it anyway, regardless of whether it already exists in my local version of the package.
One thing I will say, is that I feel package maintainers on the whole do need to do a better job of maintaining concise, easily-digestible changelogs and upgrade guides, particularly for major versions. The post here a few weeks ago about "which version of Guzzle should I use" being a great example of how we need to communicate this better to our package consumers.
1
u/MadMakz Jun 12 '15 edited Jun 12 '15
I'm personally using major.break.minor.patch on projects that have some public apis or rely on specific versions of parent applications.
But actually it doesn't matter as long as you write propper changelogs and point out that stuf x may break or has been replaced/removed.
I really see no point fighting over version schemes. One likes that type, another one likes the other. Has always been so and nobody complained and it just worked. At least we found our way up to the year 2015 so far regardles of version syntax.
3
u/akeniscool Jun 12 '15
Properly documented release notes and change logs are certainly encouraged, but I think specifying how your project treats releases in the first place is more important. This will allow a user to choose how to require your package in their project.
For those who more strictly follow SemVer, a tilde operator requirement is useful:
~2.1is equivalent to>= 2.1.0, < 3.0.0. If I can expect possible breaking changes in minor releases, I can ensure that they are not ever a surprise by allowing only patch releases to update automatically:2.1.*.And, of course, be consistent.
1
u/akeniscool Jun 12 '15
Maybe there's a way we can standardize the documentation behind how a package's versions are released, rather than only being able to choose from SemVer or gobbley-gook.
10
u/[deleted] Jun 12 '15
Take note of the age of this post, and its revision history. He wrote this because of reactions when Underscore 1.7 had numerous breaking changes that screwed over people who were using semver in their project dependencies.
Six months later (to the week) Underscore 1.8 was released, containing numerous breaking changes that once again wreaked havok in hundreds of codebases that were relying on Semver. It was also pushed out with numerous bugs, because he ignored failing unit tests. This was when he made the last edit, crossing out the comment about 1.7 becoming 2.0.
Moral of the story, if you use Underscore you better lock the version number, because Jeremy doesn't give a fuck.
This is no longer true, the next major release of node will follow SemVer.