5 ms·

Are there any projects that follow this specification strictly? It seems like most projects are willing to do backwards-incompatible "bug fixes" to the behavio

by panic 9y ago

Are there any projects that follow this specification strictly? It seems like most projects are willing to do backwards-incompatible "bug fixes" to the behavior of their API without incrementing the major version. These are usually harmless in practice, but technically break rule 8. It seems difficult to me to prove that any given set of changes can't break someone else's code (even allocating an extra byte of memory has the potential to do this).

exogen 9y ago
"Public API" is the key part of #8, not just any change that consumers could find if they tried. Is the exact number of bytes your project consumes part of the public API? If it is (and I doubt there exist many projects that would guarantee that), then yes it would be breaking.
leipert 9y ago
The problem is, that maintaining a stable API seems like not being that easy. Especially in open source projects where most of the people spend their free time and it is easy to make a tiny mistake to break an API. You asked for specific projects. I can mostly speak for the JavaScript community where React seems to be the best example. They even try to maintain compatibility between two major versions, and give good deprecation warnings. Other big projects like lodash, webpack and RxJS seem to handle it good as well. As I mentioned, React handles the migration path really well. Other projects do not provide such an easy migration between major versions...
tuupola 9y ago
In the unfashionable PHP world the Packagist libraries tend to be very strict about following semver.
- jarofgreen 9y ago
  Do you have specific examples? Given that any idiot can publish a packagist library (Hello!) that's kind of like saying "The code on GitHub does". I'll start by saying Symfony seems pretty good.
  - w0rd-driven 9y ago
    I have a specific example of one that bit me recently using Laravel, which has these doctrine dependencies upstream. On my mac I'm running php7.1 because it made sense as most of the code I write is served there now finally but there are some major projects stuck on 5.6 servers. As such I was recently bitten by this: http://doctrine-project.org/2017/07/25/php-7.1-requirement-and-composer.html http://doctrine-project.org/2017/07/25/php-7.1-requirement-a.... There about 7 packages listed there. Each github repo has at least one closed issue about this change, likely spurring the article. Knowing the fix of 'pinning' my platform to 5.6 is such an easy fix but what I had to Google to get there absolutely was not. I feel in this instance that the concept of a platform dependency like PHP is or say the underlying Node.js engine is wildly different than an upstream library. The solace I get with node is often the jump from say 4 to 8 breaks a ton of shit. The jump from PHP 5.x to 7.x breaks exactly none of my code. I believe if it had I wouldn't have jumped to it so eagerly, even though PHPStorm does a wonderful job at keeping me from using 7.x things when I specify a project is 5.6. I ultimately recognize now that I am the one that put myself in this situation but I feel like library maintainers could do a better job to prevent me from shooting myself in the foot. I know now to pin to very specific major.minor numbers at the very least and proposed that Laravel add the platform config flag to save other similar developers from making the mistake. The problem wasn't that just Laravel pinned to 1.* but that doctrine's own common package did it as well. If the platform config option didn't work another choice was to pin the specific version of upstream packages in Laravel's composer.json. That version of the fix feels like I'm ignoring most of the benefits composer was supposed to give me in the first place. I know the node ecosystem can suffer a similar fate just as easily but it feels really dirty to be in that situation. I start to wonder if I shouldn't be using those packages at all.
jrochkind1 9y ago
I feel like a lot of things, at least in ruby world where I mostly work, have gotten a _lot_ better in the past few years. "Strictly"? Well, backwards compat mistakes can happen, but mistakes can always happen. Other than that, it's the difficulty of knowing what is the "public API". It's a time-consuming and difficult task to be clear about this. But I think semver has spurred people to try harder and get closer.
bartread 9y ago
The thing I find most frustrating about semantic version is that even under the strictest adoption it overly legitimizes breaking changes across major versions. I see far too much refactoring of JS library APIs that is essentially aesthetic across major versions - D3 and Angular spring immediately to mind (I understand the scalability justification for Angular; I just don't really believe it). To me, having an elegant API is not the highest concern because what I'm interested in is building products, and from that point of view stability is much more important. I do not appreciate a committee of J Random JavaScript Developers randomly dumping extra work into my product backlog because they didn't like the cut of an API's jib, especially when these people have gone absolutely out of their way to drive adoption in the first place. To give a counter-example: .NET code I wrote in the mid-noughties whilst working at Red Gate still runs today, substantially unmodified. Some of that stuff is 11 or 12 years old. SQL Dependency Tracker is the most obvious example, because the product hasn't changed much since 2006, except for additions to support new object types in new versions of SQL Server. The fact that new .NET versions haven't broken the product has obviously made it much easier to support through the years.
- gizmo686 9y ago
  That is the entire point of the major version. The fact is, developers sometimes make breaking changes (sometimes for good reasons, sometimes for bad), and we want a standard way of documenting that. If you don't make breaking changes, than stay on 1.X.Y forever. If your project is only a year old and already on version 10.0.0, you are probably doing something wrong; but at least documenting it in your version numbers.
  - bartread 9y ago
    Certainly take your point, and maybe it's in part down to my background, where a new major version generally includes some large chunk of new functionality (regardless of whether or not there are breaking changes). And really I suppose you don't ever need to go beyond version 1.x.y. Window Maker is quite a good example of this: latest version is 0.95.8 after 20 years of development.
- fenomas 9y ago

by panic 9y ago

exogen 9y ago

"Public API" is the key part of #8, not just any change that consumers could find if they tried. Is the exact number of bytes your project consumes part of the public API? If it is (and I doubt there exist many projects that would guarantee that), then yes it would be breaking.

leipert 9y ago

The problem is, that maintaining a stable API seems like not being that easy. Especially in open source projects where most of the people spend their free time and it is easy to make a tiny mistake to break an API. You asked for specific projects. I can mostly speak for the JavaScript community where React seems to be the best example. They even try to maintain compatibility between two major versions, and give good deprecation warnings. Other big projects like lodash, webpack and RxJS seem to handle it good as well. As I mentioned, React handles the migration path really well. Other projects do not provide such an easy migration between major versions...

tuupola 9y ago

In the unfashionable PHP world the Packagist libraries tend to be very strict about following semver.

jarofgreen 9y ago
Do you have specific examples? Given that any idiot can publish a packagist library (Hello!) that's kind of like saying "The code on GitHub does". I'll start by saying Symfony seems pretty good.
- w0rd-driven 9y ago
  I have a specific example of one that bit me recently using Laravel, which has these doctrine dependencies upstream. On my mac I'm running php7.1 because it made sense as most of the code I write is served there now finally but there are some major projects stuck on 5.6 servers. As such I was recently bitten by this: http://doctrine-project.org/2017/07/25/php-7.1-requirement-and-composer.html http://doctrine-project.org/2017/07/25/php-7.1-requirement-a.... There about 7 packages listed there. Each github repo has at least one closed issue about this change, likely spurring the article. Knowing the fix of 'pinning' my platform to 5.6 is such an easy fix but what I had to Google to get there absolutely was not. I feel in this instance that the concept of a platform dependency like PHP is or say the underlying Node.js engine is wildly different than an upstream library. The solace I get with node is often the jump from say 4 to 8 breaks a ton of shit. The jump from PHP 5.x to 7.x breaks exactly none of my code. I believe if it had I wouldn't have jumped to it so eagerly, even though PHPStorm does a wonderful job at keeping me from using 7.x things when I specify a project is 5.6. I ultimately recognize now that I am the one that put myself in this situation but I feel like library maintainers could do a better job to prevent me from shooting myself in the foot. I know now to pin to very specific major.minor numbers at the very least and proposed that Laravel add the platform config flag to save other similar developers from making the mistake. The problem wasn't that just Laravel pinned to 1.* but that doctrine's own common package did it as well. If the platform config option didn't work another choice was to pin the specific version of upstream packages in Laravel's composer.json. That version of the fix feels like I'm ignoring most of the benefits composer was supposed to give me in the first place. I know the node ecosystem can suffer a similar fate just as easily but it feels really dirty to be in that situation. I start to wonder if I shouldn't be using those packages at all.

jrochkind1 9y ago

I feel like a lot of things, at least in ruby world where I mostly work, have gotten a _lot_ better in the past few years. "Strictly"? Well, backwards compat mistakes can happen, but mistakes can always happen. Other than that, it's the difficulty of knowing what is the "public API". It's a time-consuming and difficult task to be clear about this. But I think semver has spurred people to try harder and get closer.

bartread 9y ago

The thing I find most frustrating about semantic version is that even under the strictest adoption it overly legitimizes breaking changes across major versions. I see far too much refactoring of JS library APIs that is essentially aesthetic across major versions - D3 and Angular spring immediately to mind (I understand the scalability justification for Angular; I just don't really believe it). To me, having an elegant API is not the highest concern because what I'm interested in is building products, and from that point of view stability is much more important. I do not appreciate a committee of J Random JavaScript Developers randomly dumping extra work into my product backlog because they didn't like the cut of an API's jib, especially when these people have gone absolutely out of their way to drive adoption in the first place. To give a counter-example: .NET code I wrote in the mid-noughties whilst working at Red Gate still runs today, substantially unmodified. Some of that stuff is 11 or 12 years old. SQL Dependency Tracker is the most obvious example, because the product hasn't changed much since 2006, except for additions to support new object types in new versions of SQL Server. The fact that new .NET versions haven't broken the product has obviously made it much easier to support through the years.

gizmo686 9y ago
That is the entire point of the major version. The fact is, developers sometimes make breaking changes (sometimes for good reasons, sometimes for bad), and we want a standard way of documenting that. If you don't make breaking changes, than stay on 1.X.Y forever. If your project is only a year old and already on version 10.0.0, you are probably doing something wrong; but at least documenting it in your version numbers.
- bartread 9y ago
  Certainly take your point, and maybe it's in part down to my background, where a new major version generally includes some large chunk of new functionality (regardless of whether or not there are breaking changes). And really I suppose you don't ever need to go beyond version 1.x.y. Window Maker is quite a good example of this: latest version is 0.95.8 after 20 years of development.
fenomas 9y ago