6 ms·

Semantic Versioning 2.0.0 (2013)

50 points by jbernardo95 9y ago

Dreami 9y ago
We probably need a changelog
- deleted 9y ago
  [deleted]
- jrochkind1 9y ago
  http://keepachangelog.com/en/1.0.0/ http://keepachangelog.com/en/1.0.0/
STRML 9y ago
See https://github.com/mojombo/semver/compare/v1.0.0...v2.0.0 https://github.com/mojombo/semver/compare/v1.0.0...v2.0.0 for the changelog. Edit: Changes, that is, not a changelog.
- CaliforniaKarl 9y ago
  I don't think that's a changelog. That is a collection of git commits, where the intended audience is primarily the developers of the work. A changelog, by comparison, is meant for clients who use the work. See also https://github.com/mojombo/semver/issues/387 https://github.com/mojombo/semver/issues/387 and http://keepachangelog.com/en/1.0.0/ http://keepachangelog.com/en/1.0.0/
  - STRML 9y ago
    Yes, you're correct, it's not a changelog - rather, it is the changes. Click "Files changed" for an actual diff. I am not sure what makes it v2.0.0, however.
mmebane 9y ago
This appears to be from 2013: https://github.com/mojombo/semver/commits/v2.0.0 https://github.com/mojombo/semver/commits/v2.0.0
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.
SimonPStevens 9y ago
I've been at so many companies where someone is pushing to adopt semantic versioning without actually following step 1 in the spec... > 1. Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive. SemVer doesn't even make sense if you don't have a public API. SemVer doesn't make sense for end user products that don't have an API. I really wish people would stop trying to abuse it.
- deleted 9y ago
  [deleted]
- dudul 9y ago
  I'm pretty sure they mean "API" in its true sense. An API for a module or a library, not necessarily a Web API. It's not unusual for an organization to maintain several projects/libraries/services that interact internally via their APIs (sometimes over HTTP, sometimes directly as a library), SemVer makes perfect sense for this use case.
  - SimonPStevens 9y ago
    Yeah, which is fine if that's what you do. You can take 'public' to have whatever meaning works for you. I'm talking about places that try and apply SemVer to their consumer facing product, that has no API. That doesn't make sense.
  - fenomas 9y ago
    They mean API in the sense of anything that someone can declare a dependency against. Whether it's a web service or a library is immaterial; the point of the thing is to be able to update something and formally tell any downstream dependencies whether the update breaks compatibility or not.
eggs_and_avo 9y ago
Check out Compatible Versioning 1.0 (2016): https://github.com/staltz/comver https://github.com/staltz/comver

50 points by jbernardo95 9y ago

Dreami 9y ago

We probably need a changelog

deleted 9y ago
[deleted]
jrochkind1 9y ago
http://keepachangelog.com/en/1.0.0/ http://keepachangelog.com/en/1.0.0/

STRML 9y ago

See https://github.com/mojombo/semver/compare/v1.0.0...v2.0.0 https://github.com/mojombo/semver/compare/v1.0.0...v2.0.0 for the changelog. Edit: Changes, that is, not a changelog.

CaliforniaKarl 9y ago
I don't think that's a changelog. That is a collection of git commits, where the intended audience is primarily the developers of the work. A changelog, by comparison, is meant for clients who use the work. See also https://github.com/mojombo/semver/issues/387 https://github.com/mojombo/semver/issues/387 and http://keepachangelog.com/en/1.0.0/ http://keepachangelog.com/en/1.0.0/
- STRML 9y ago
  Yes, you're correct, it's not a changelog - rather, it is the changes. Click "Files changed" for an actual diff. I am not sure what makes it v2.0.0, however.

mmebane 9y ago

This appears to be from 2013: https://github.com/mojombo/semver/commits/v2.0.0 https://github.com/mojombo/semver/commits/v2.0.0

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.

SimonPStevens 9y ago

I've been at so many companies where someone is pushing to adopt semantic versioning without actually following step 1 in the spec... > 1. Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive. SemVer doesn't even make sense if you don't have a public API. SemVer doesn't make sense for end user products that don't have an API. I really wish people would stop trying to abuse it.

deleted 9y ago
[deleted]
dudul 9y ago
I'm pretty sure they mean "API" in its true sense. An API for a module or a library, not necessarily a Web API. It's not unusual for an organization to maintain several projects/libraries/services that interact internally via their APIs (sometimes over HTTP, sometimes directly as a library), SemVer makes perfect sense for this use case.
- SimonPStevens 9y ago
  Yeah, which is fine if that's what you do. You can take 'public' to have whatever meaning works for you. I'm talking about places that try and apply SemVer to their consumer facing product, that has no API. That doesn't make sense.
- fenomas 9y ago
  They mean API in the sense of anything that someone can declare a dependency against. Whether it's a web service or a library is immaterial; the point of the thing is to be able to update something and formally tell any downstream dependencies whether the update breaks compatibility or not.

eggs_and_avo 9y ago

Check out Compatible Versioning 1.0 (2016): https://github.com/staltz/comver https://github.com/staltz/comver