mirror of
https://github.com/semver/semver.git
synced 2026-03-22 14:10:15 -05:00
Is API really required? #226
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#226
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 @ZeroUnderscoreOu on GitHub (Jun 10, 2016).
Does this mean that I'm not allowed to use SemVer for a standalone project that doesn't expose anything?
@FichteFoll commented on GitHub (Jun 10, 2016):
SemVer is primarily designed for dependencies, i.e. something others depend on such as a library or package. You can, of course, also follow its spirit for non-dependency things, in which case the "API" thing becomes a very subjective thing.
SemVer intentionally does not make any effort in trying to apply to all use cases, such as for programs for the end user.
@ZeroUnderscoreOu commented on GitHub (Jun 10, 2016):
What confuses me the most is the prohibition. I'm not even going to ask what kind of differences in versioning should I make or if someone's going to sue me for misuse (kidding), but why prohibit it at all?
That basically means that I'm not "licensed" to use it, so I have to either make something up myself or look for another spec (which I not know of).
What's also interesting is that exposing even a dummy and completely unrequired API makes any project compliant.
And finally, which is my particular case, versioning of JPM Gecko add-ons requries use of SemVer, when browser add-ons hardly expose anything beyond UI. (As far as I understand this goes from Node.js's versioning requirements, but still it extends usage of SemVer out of API-only).
@BurtHarris commented on GitHub (Jun 17, 2016):
I think that "API" has to be interpreted broadly: perhaps as a comprehensive and precise set of conventions that software outside a package needs to understand to use and upgrade the package properly. Add-ons typically both implement and consume APIs in the sense that rule #1 uses the term. The intent of rule #1 is more to say that semantic versioning rules for reusable software packages are distinct from choices made related to the "marketing version" of a product, and that we don't apply them to things like say sunglasses or lawnchairs.
@JacksonBailey commented on GitHub (Jul 11, 2016):
I agree with BurtHarris, API is a broad definition. If you have no sort of API (or declared way with which your software must be interacted with) then there is literally no point to be using semantic versioning.
If versioned software falls in the middle of the woods, and no one is around to use it, can it make a backwards incompatible change?
@ZeroUnderscoreOu commented on GitHub (Jul 12, 2016):
@JacksonBailey well, I have at least 2 reasons to use SemVer even if it's not designed for my type of project:
@JacksonBailey commented on GitHub (Jul 12, 2016):
You can still use it, there's nothing stopping you. There's no semver police that will come and get you. It's just that semver is to communicate changes in the API (or more generally how a thing is used). Also, if you have no declared way of how your stuff is to be interacted with, every release is by definition only required to be a patch release (because the API is never growing nor ever backwards incompatible).
I get where you're coming from with this issue making it sound like you're not allowed to use it if you don't have an API, but I think it's more to say that the API must be public and specified as opposed to private or undocumented.
@israel-lugo commented on GitHub (Sep 20, 2016):
I think that in @ZeroUnderscoreOu's case, if nothing else, the UI would qualify as the "API". That is, in the broader sense: the way other things (programs, libraries, humans) can interact with this software.
For me, it makes perfect sense e.g. for a CLI tool to use SemVer. As a human user, I am supposed to interact with the program, i.e. by using the
--foooption to enable Fooing and the--bar=5option to limit Bars to 5. If a new version of the program no longer allows you to Foo (the--foooption is gone), then I would say that is a "breaking change in the API".Perhaps the problem here is in with the AP in API. I would suggest that the more generic term Interface would be much more appropriate.
@zafarkhaja commented on GitHub (Sep 20, 2016):
I agree with @FichteFoll, API is the most appropriate term here, the other options like "interface" or "set of conventions" are too abstract for a specification. The P in API is intentional, SemVer has a well-defined format for a reason, so that we can interpret it programmatically. For something used by humans we have other options to convey the nature of changes, in a natural language.
@FichteFoll commented on GitHub (Sep 20, 2016):
I'd be okay with "interface", but I fear that this would be misunderstood.
@israel-lugo commented on GitHub (Sep 20, 2016):
@zafarkhaja I understand what you mean regarding the well defined format. After all, the very premise behind SemVer is to define a precise format to attribute semantic meaning to the version numbers. Please note, however, that this in no way precludes interpretation by a human being. In fact, I would submit that the main point behind all of this is precisely to convey useful information to the users of your project -- whether the user be a developer integrating your library in his program, or an end user clicking on your program's buttons.
Yes, SemVer allows us to programmatically implement straightforward dependency rules, e.g. in a package manager automatically handling dependencies. That comes from the well defined format. But it would be, in my opinion, a far too limited view to only think of this in terms of build scripts and DEB packages. All of those tools exist to serve us, the humans. Not the other way around.
It is important for me, as a developer, to know that I can use the new classes and methods in your libfoo-1.2.0 without worrying about something else breaking from what I had already written for libfoo-1.1.0. That's critically useful information for me, a human developer.
Likewise, it is important for me, a systems administrator, to know that I can safely upgrade your httpd-2.1.1 to httpd-2.1.2 without worrying about disrupting service because some configuration file syntax changed in a non-compatible way. That's critically useful information for me, a human sysadmin.
And finally, it is important for me, a user of computers, to know that I better read the release notes when upgrading from svgeditor-1.7.0 to svgeditor-2.0.0, because something important changed and maybe I can't save directly to Ghostscript anymore.
Of all these cases, only the first one is fully described by the name "Application Programmer Interface".
@israel-lugo commented on GitHub (Sep 20, 2016):
@FichteFoll: perhaps we can reach a better name, then.
In my opinion, an "interface" is a very well defined concept in computer science (and in engineering in general), as a point of interaction between two separate components of a system. It seems to me to describe well what we are talking about here. However, if there are doubts, surely together we can think of a better way.
@jwdonahue commented on GitHub (Nov 29, 2017):
I think API is too restrictive. I have developed tooling in the past that uses SemVer to do version control of large sets of build tools. We needed to get binaries out of our source revision system and had a deduping file system service available (on top of the Azure blob store), so we developed a mapping between SemVer strings and the file systems "pathy" identifiers and started packing up sets of compilers and linkers into this system. We were essentially versioning our entire build system with this scheme.
I like Interface over API because my research of the term takes me to fewer places:
-- https://en.wikipedia.org/wiki/Interface_(computing)
-- https://en.wikipedia.org/wiki/User_interface
-- https://en.wikipedia.org/wiki/Protocol_(object-oriented_programming)
-- https://en.wikipedia.org/wiki/Application_programming_interface
-- https://en.wikipedia.org/wiki/Application_binary_interface
Notice that all of the items listed on Wikipedia's Interface disambiguation page, under Computing fall into the category of things that can be versioned using the SemVer spec, if you replace API with Interface.
@israel-lugo commented on GitHub (Nov 30, 2017):
100% agreed, @jwdonahue. In fact, I had opened issue #331 precisely to suggest changing API with Interface. Perhaps your use case would be a good example to add there.
@jwdonahue commented on GitHub (Nov 30, 2017):
@israel-lugo, yup, sorry, I meant to reply on that thread actually. Is there a way to link to it or should I just copy/past the above into your thread?
@israel-lugo commented on GitHub (Nov 30, 2017):
@jwdonahue Actually I don't know how to do that, other than by copying the full URL of the comment, i.e. https://github.com/semver/semver/issues/314#issuecomment-348023713 (I got this URL by right clicking on the "a day ago" part, above your comment. That is, "jwdonahue commented a day ago".
@jwdonahue commented on GitHub (Nov 30, 2017):
Ok, I am going to gather up all of the "API should be..." type issues in a single a bug and push for a fix or won't fix so we can settle this matter.
@jwdonahue commented on GitHub (Oct 9, 2018):
@ZeroUnderscoreOu
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.