mirror of
https://github.com/semver/semver.git
synced 2026-07-11 06:53:03 -05:00
[GH-ISSUE #90] Other then "Public API" can still use semver.org? #1799
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#1799
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 @cies on GitHub (Apr 29, 2013).
Original GitHub issue: https://github.com/semver/semver/issues/90
It comes out of a practical example where I've used semver to over more then then "Public API". Cases of things that need to be kept stable within a major-cycle:
Maybe semver could be formulated in a way that it shows it naturally covers more the just "public API".
@jeffhandley commented on GitHub (Apr 30, 2013):
Seems pretty reasonable. Suggestion on the wording to change?
@cies commented on GitHub (Apr 30, 2013):
No not really.. Obviously I thought about it, but it seems that saying "we use semver" is not enough; semver users need to say "our XYZ is/are covered by semver, such that ..."
The wording could change in the following ways:
But in either case the projects that use semver need to describe what semver is covering.
@rkh commented on GitHub (May 1, 2013):
Wouldn't be things like the DB schema, file formats etc not simply become part of the public API in that case?
@Tieske commented on GitHub (May 1, 2013):
this issue has 2 elements
former: this is a scoping issue. Whenever you define a version, the author should make very clear what the scope of the version numbering is. In the example given; database schema and file formats, they both get their own version. And the overall product gets its own version. Each on their own scope incremented when something changes.
latter: I think the wording could be changed, or something added, that says that the versioning scheme may also be usefull outside of the software development world. Documents, drawing, product designs, whatever.
@cies commented on GitHub (May 2, 2013):
Thank you Tieske, good input. I like the breakdown you found.
Both 1 and 2 imply that "public API" in the semver text means something else then what public API strictly stands for.
I think the power of semver lies in what x, y and z mean. This only makes sense for "things" that:
The best word I can think up for a "thing" that semver covers is: convention. All of public APIs, db schemas, file formats and protocols are in a way conventions, right?
Semver expresses something about conventions that dependents of those conventions can derive from what they have to do in order to accept other (usually newer) versions of that convention. It does so by adding SEMantics to the VERsioning scheme.
@nicolas-miari commented on GitHub (Dec 24, 2013):
What if your software is aimed at end users exclusively (e.g., a game)? What does "Public API" mean in this context? What should "Backwards compatibility" mean?
@cies commented on GitHub (Jan 13, 2014):
Good point. If I reflect on your words: UI can also be covered by semver.
A UI can be improved without breaking something (fixing a UI-glitch, Z); it can be extended without changing the current UI elements (Y); and, it can be chaning in way that you need to relearn part of the UI (X).
(In X.Y.Z)
@doingweb commented on GitHub (Jan 14, 2014):
Perhaps "Public API" can be generalized to "interface" (conventions of interaction). That word seems to encompass all of the "things" we're talking about - APIs, database schemas, file formats, protocols, UIs, etc. - the boundaries between our system and external consumers. Any type of interface is subject to change, and therefore is useful to consumers to be semver'd.
@korneel commented on GitHub (Mar 7, 2014):
I agree on "interface" being a better word than "public API". A GUI is not an application programming interface.
@crazedsanity commented on GitHub (Mar 7, 2014):
+1 on "interface" vs "public API"
@cies commented on GitHub (Mar 9, 2014):
Another one for "interface". I think some further explanation is needed; (1) to give some examples of "interfaces" (API, db schema, protocol, GUI, etc.), and (2) that one program can employ several several versions for different "interfaces".
@tbull commented on GitHub (Mar 9, 2014):
+1
@cies commented on GitHub (Mar 12, 2014):
I just "Generalized the text to 'interfaces'". Please let me know what you think about it. On line 38-41 and 74-76 of the original file you find the --in my opinion-- most significant changes in the diff.
@chriskempson commented on GitHub (Mar 19, 2014):
+1 👍
@Tieske commented on GitHub (Jun 24, 2014):
@nicolas-miari
I think this is an invalid question. Simply because before implementing semver on 'something', you should have a need for it. So just the end-user game doesn't make sense to apply semver. But when it uses some scripting for extending the game, then that API could be covered by SemVer (and hence also the entire game itself). It all comes back to scoping.
@crazedsanity commented on GitHub (Jun 24, 2014):
@Tieske in the context of a game, there's still the need for a version. In the event that only one version is ever released, that's just fine. But if there are updates, then there's validity in whether or not it is backwards-compatible... so a bugfix might be
v1.0.1, but a more important change might bev1.1.0. If it is an entirely new version of the game, or the change requires completely removing the old version to install this new version, then it might bev2.0.0. There's still use for SemVer. Releasing any package without at least a rudamentary version is a really, really, REALLY bad idea IMHO.@Tieske commented on GitHub (Jun 24, 2014):
Now you are describing usecase, and now semver makes sense (though I think that in this case the marketing dept. has a bigger say in this than the developmentteam). That is exactly my point, is all about scoping, and @nicolas-miari question didn't have a proper scope.
@cies commented on GitHub (Jun 24, 2014):
Since this thread lights up again, please have a look at my pull-request on this issue.
I think it pretty much resolves it: all the text's scope specifications such as "public API" and/or "package", have been changed to "interface". As an added bonus it makes wording a little more strict (in terms of RFC-2119; MAY, SHOULD, MUST, etc.) where possible.
Lately I see semver being used all over the place; I think this is a very useful generalization of the spec, paving the road for even wider adoption.
@mojombo writes on the similar natured issue #13 (which he then closed), the following:
I think the "if you can figure out" ambiguity is not appropriate for a spec that is as widely applicable, and used(!), as semver.
@nicolas-miari commented on GitHub (Jun 25, 2014):
@Tieske I don't really understand what you mean by "scope" here, but I disagree (and agree with @crazedsanity) with your statement that for end user-facing application software like games, semantic versioning doesn't make sense: unlike the console games of yesteryear, baked forever on a cartridge/CD/etc, games are updated and maintained (especially if they rely on a server side component).
I, too, am all for "interface" vs. "API".
@Tieske commented on GitHub (Jun 27, 2014):
@nicolas-miari the question "your software is aimed at end users exclusively " is so generic that its impossible to answer whether semver applies. To use semver you need to be specific about what it covers and what it doesn't. eg. the scope of what semver covers for your use case.
And then if you apply it to a game that gets updates etc, then semver it a perfectly viable solution for dependency checks etc.
@maximal commented on GitHub (Jun 30, 2014):
interface@ameenross commented on GitHub (Dec 19, 2014):
Why not leave it up to the project to define whether it defines and documents a
... or a combination of? I think the question
Does your project require semver?is flawed. The question should beWould semver make life easier while working on your project?. I think for most people the answer to that last question is "yes".@jwdonahue commented on GitHub (Dec 1, 2017):
See also:
#90
#314
#331
#156
@silkentrance commented on GitHub (Dec 7, 2017):
Why is this still open? SEMVER is about an abstract versioning process. ABSTRACT means stable. What is proposed here is barely stable. We do not need such. We want stable processes. And we also do not want peops who cannot cope with stable processes. Go back into your rabbit holes, multiply and have fun, but stay there.
@ameenross commented on GitHub (Dec 7, 2017):
Who's "we"? Go tell the PKZIP guys (and countless others) that they didn't build something stable...
You can stick to Semver as currently defined, some of us want to be able to say that our (file format|db schema|API|protocol|whatever) adheres to semver s/public API/interface/
@cies commented on GitHub (Dec 7, 2017):
Well said @ameenross
This is exactly what I meant. A single codebase might use semver in several places, for instance: it has a file format, and library API and a web API.
Now I do not have a problem with using semver in its current form for these purposes, I'll just make it clear in the README (or other documentation) that "pub API" in the semver spec should be read as XYZ.
I simply regret that semver is not advertising that it can be used for many more purposes.
@jwdonahue commented on GitHub (Dec 7, 2017):
@silkentrance, I agree that we have too many of these old threads laying around, but I have not completed my review of all the open issues yet, so I have not recommended closing this particular issue, until I have gathered all the seemingly worthy similar instances of "API should be changed to X". When I do, I'll pick one that is sufficiently representative or write one up if needed, and then ask for all the me-too's to be closed. I can think of strong arguments to replace most instances in the spec of API with Interface. It seems to be a valid open issue to me.
@jwdonahue commented on GitHub (Oct 9, 2018):
@cies
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.
@cies commented on GitHub (Oct 9, 2018):
Closed in favour of #468