mirror of
https://github.com/semver/semver.git
synced 2026-03-09 07:22:04 -05:00
You should make it clear that you are talking about Package versioning and not API versioning #99
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#99
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 @jdubray on GitHub (Aug 22, 2013).
Tom,
with all due respect your recommendation is dangerous and will fail people who use it. My understanding is that you translated your development experience in the world of APIs, unfortunately, it does not work that way.
There are at least 3 problems with your recommendation.
The first one is relative to #3. You are recommending what is called an "immutable" versioning strategy. That approach will kill you. I have seen several organizations adopting that approach and it looks like for v1,2 and 3, after a couple of years you have between 15 and 30 "immutable" versions in production and as you can easily imagine as a Service/API provider you are dead
The second one is that none of your recommendation are made at the protocol level, if you ever had implemented your recommendation you would realize that you need two kinds of versions, one that identifies the service/API and the other one that identifies when the client was built (i.e. what version of the service was in effect when the client was built). That's why people use major and minor version. The bottom line is that the service/API does not care about the client version, it only cares to know which version of the service was in effect when the client was built.
The third problem is that you make no distinction between forward and backward compatibility. Again, developers tend to dismiss the distinction as it does not really appear in traditional development. If you want to convince yourself of the difference between the two, I would recommend you think about your favorite office suite opening a particular document and how document versions and client versions relate.
I believe your recommendation is more than counterproductive and should be removed altogether until you understand the principles of API versioning.
Jean-Jacques Dubray
http://www.infoq.com/articles/contract-versioning-comp2
@Oxymoron290 commented on GitHub (Aug 28, 2013):
http://barelyenough.org/blog/2008/05/resthttp-service-versioning-reponse-to-jean-jacques-dubray/
@jdubray commented on GitHub (Aug 28, 2013):
Please read the comments of this post.
"..., in general you will need Major and Minor -of course. What I am saying is that the inter-action between two software agents require that you identify the exact version of the requestor/consumer and the major version of the responder/provider.
I could I have a request v2.x sent to a service v2.y. The requestor MUST announce its version, while it targets a major version of a provider (the goal of forwards compatibility is to let the provider upgrade without ANY change to the existing resource consumers).
Unless I am mistaken your versioning scheme only supports conveying the version of the service provider/responder. This is actually an “odd” design because it is the requestor that says “I really want to talk to v2.1″. This is counter to “forwards compatibility” requirements."
@Oxymoron290 commented on GitHub (Aug 28, 2013):
I'm guessing this issue is reguarding an SOA? If so, please update the title.
From my understanding, this versioning is focused on packages and dependent packages
@jdubray commented on GitHub (Aug 28, 2013):
I updated the title. I would also recommend the description of your approach to emphasize the fact that it applies to packages and not API version. The text is very ambiguous and some very senior people I know suggested we use your versioning scheme to deal with APIs.
For instance, this recommendation applied to APIs does not work:
"For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version."
@EddieGarmon commented on GitHub (Aug 28, 2013):
@jdubray I believe that you have a misunderstanding about how to version services in general.
The first issue is immutable versions are exactly what you want when you are referring to an API, be it a library, package, specification, or remote service. Just because versions are immutable, does not and absolutely should not prevent you from having a deprecation and removal plan for retired APIs. (or hosted services in your case)
The second issue is that APIs don't give a rats arse what the version number of the caller is. If you need to log information about the caller, that information needs to be passed into your API somehow as a part of the API itself.
Maybe this is just a :trollface: ?
@jdubray commented on GitHub (Aug 28, 2013):
Well, your response is quite ironic. We'll have to agree to disagree, I wish the best of luck to whoever follows this recommendation.
@jdubray commented on GitHub (Aug 29, 2013):
In the end, there are only 3 ways to manage API versioning:
In general, with a bit of foresight, you need to create a major version every 9-12 months, if you keep 3 in production as a goal, that gives plenty of time for clients to upgraded when it is convenient to them.
The reason why the client needs to explicitly provide the minor version on which it was built is the same reason why we have an User-Agent HTTP header, because the server / API can be a tiny bit smart about what to do with the request. Imagine a world where we would have to expose specific endpoints for every version of every browser ... well that's kind of the world that you are building when you are not able to deal with small variations based on the knowledge of the minor version the client was built on.
I have also seen people versioning individual endpoints rather than the entire API/Service. That will kill both your ecosystem and yourself.
Again, the semver recommendation simply does not reflect the body of knowledge that folks built over the years. It works well for code and packages, no question there, IT SIMPLY DOES NOT WORK FOR API VERSIONING.
@denis-sokolov commented on GitHub (Sep 5, 2013):
@jdubray You do realize that "code and packages" have APIs as well?
@jwdonahue commented on GitHub (Dec 2, 2017):
Related:
#90
#314
#331
#459
@jwdonahue commented on GitHub (Dec 2, 2017):
@jdubray, unless you have any actionable requests to add here, please close this issue at your earliest possible convenience.
@jwdonahue commented on GitHub (Oct 9, 2018):
@jdubray
I've tried to consolidate all of the "API should be changed X" and similar issues into #468. Please contribute to this discussion on that thread and close this one at your earliest possible convenience.
Thank you.
@jwdonahue commented on GitHub (Jan 16, 2020):
@jdubray, unless you intend to follow the process outlined in the CONTRIBUTING.md and issue an RFC, or you have further questions, please close this issue at your earliest possible convenience.
@alexandrtovmach commented on GitHub (Jun 10, 2020):
Closed in favor #468