Other then "Public API" can still use semver.org? #90

Open
cies opened this Issue Apr 29, 2013 · 23 comments

Projects

None yet
@cies
cies commented Apr 29, 2013

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:

  • database schema (should be migrateable from any to any version within a major-cycle with the standard migration runner)
  • file formats (only non breaking additions/changes allowed within major-cycle)
  • network protocols
  • API-calls it makes on other systems (just as much public API actually)

Maybe semver could be formulated in a way that it shows it naturally covers more the just "public API".

@wookietreiber

👍

@jeffhandley
Contributor

Seems pretty reasonable. Suggestion on the wording to change?

@cies
cies commented 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:

  • saying that "public API" can be broadly interpreted (giving some examples to explain)
  • replacing "public API" with something that is not so specific

But in either case the projects that use semver need to describe what semver is covering.

@rkh
rkh commented 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
Contributor
Tieske commented May 1, 2013

this issue has 2 elements

  1. a public API that comprises multiple, individually versioned, elements
  2. can SemVer be applied to other stuff than software API's

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
cies commented 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:

  • have other things depend on them (public APIs, db schemas, file formats, protocols, etc.)
  • can change in a way it breaks the proper functioning of the dependent things (in which case x needs to be upped)
  • can change in a way it should not break the proper functioning of the dependent things (y needs upped)
  • can change is a way the thing the version number covers is not actually affected (z needs upped)

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

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
cies commented 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

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
korneel commented Mar 7, 2014

I agree on "interface" being a better word than "public API". A GUI is not an application programming interface.

@crazedsanity

+1 on "interface" vs "public API"

@cies
cies commented 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
tbull commented Mar 9, 2014

+1

@cies cies added a commit to cies/semver that referenced this issue Mar 12, 2014
@cies cies Generalized the text to "interfaces"
The version of the text describes "interfaces" instead of merely "public APIs", as discussed in #90. I also upcased some RFC2119-words, and changed some text into the passive voice (not complete, only where it touched the text I was changing anyway). Tried not to fix line-wrap to ease diff'ing for humans.
4e95d51
@cies
cies commented 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

+1 👍

@cies cies referenced this issue in mojombo/semver.org Apr 4, 2014
Closed

semver seems to be geared at libraries, am i right? #18

@Tieske
Contributor
Tieske commented Jun 24, 2014

@nicolas-miari

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?

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

@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 be v1.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 be v2.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
Contributor
Tieske commented 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
cies commented 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:

If you can figure out a way to pin down something akin to an API, then you can apply the principles of SemVer. Some things are better fits than others. If it's a useful construct, go for it.

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

@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
Contributor
Tieske commented 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
maximal commented Jun 30, 2014

interface

@ameenross

Why not leave it up to the project to define whether it defines and documents a

  • GUI
  • CLI
  • API
  • DB Schema
  • File format
  • Protocol

... or a combination of? I think the question Does your project require semver? is flawed. The question should be Would semver make life easier while working on your project?. I think for most people the answer to that last question is "yes".

@czlee czlee referenced this issue in czlee/tabbycat Jul 25, 2015
Closed

Semantic versioning convention #216

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment