New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

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

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".

@jeffhandley

This comment has been minimized.

Show comment
Hide comment
@jeffhandley

jeffhandley Apr 30, 2013

Contributor

Seems pretty reasonable. Suggestion on the wording to change?

Contributor

jeffhandley commented Apr 30, 2013

Seems pretty reasonable. Suggestion on the wording to change?

@cies

This comment has been minimized.

Show comment
Hide comment
@cies

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

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

This comment has been minimized.

Show comment
Hide comment
@rkh

rkh 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?

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

This comment has been minimized.

Show comment
Hide comment
@Tieske

Tieske May 1, 2013

Contributor

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.

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

This comment has been minimized.

Show comment
Hide comment
@cies

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

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

This comment has been minimized.

Show comment
Hide comment
@nicolas-miari

nicolas-miari 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?

nicolas-miari commented 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

This comment has been minimized.

Show comment
Hide comment
@cies

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

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

This comment has been minimized.

Show comment
Hide comment
@doingweb

doingweb 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.

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

This comment has been minimized.

Show comment
Hide comment
@korneel

korneel Mar 7, 2014

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

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

This comment has been minimized.

Show comment
Hide comment
@crazedsanity

crazedsanity Mar 7, 2014

+1 on "interface" vs "public API"

crazedsanity commented Mar 7, 2014

+1 on "interface" vs "public API"

@cies

This comment has been minimized.

Show comment
Hide comment
@cies

cies 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".

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

This comment has been minimized.

Show comment
Hide comment
@tbull

tbull commented Mar 9, 2014

+1

cies added a commit to cies/semver that referenced this issue Mar 12, 2014

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.
@cies

This comment has been minimized.

Show comment
Hide comment
@cies

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

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

This comment has been minimized.

Show comment
Hide comment
@chriskempson

chriskempson commented Mar 19, 2014

+1 👍

@Tieske

This comment has been minimized.

Show comment
Hide comment
@Tieske

Tieske Jun 24, 2014

Contributor

@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.

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

This comment has been minimized.

Show comment
Hide comment
@crazedsanity

crazedsanity 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 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.

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

This comment has been minimized.

Show comment
Hide comment
@Tieske

Tieske Jun 24, 2014

Contributor

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.

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

This comment has been minimized.

Show comment
Hide comment
@cies

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

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

This comment has been minimized.

Show comment
Hide comment
@nicolas-miari

nicolas-miari 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".

nicolas-miari commented 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

This comment has been minimized.

Show comment
Hide comment
@Tieske

Tieske Jun 27, 2014

Contributor

@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.

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

This comment has been minimized.

Show comment
Hide comment
@maximal

maximal Jun 30, 2014

interface

maximal commented Jun 30, 2014

interface

@ameenross

This comment has been minimized.

Show comment
Hide comment
@ameenross

ameenross Dec 19, 2014

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".

ameenross commented Dec 19, 2014

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".

@jwdonahue

This comment has been minimized.

Show comment
Hide comment
@jwdonahue

jwdonahue Dec 1, 2017

Contributor

See also:
#90
#314
#331
#156

Contributor

jwdonahue commented Dec 1, 2017

See also:
#90
#314
#331
#156

@silkentrance

This comment has been minimized.

Show comment
Hide comment
@silkentrance

silkentrance 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.

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

This comment has been minimized.

Show comment
Hide comment
@ameenross

ameenross 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/

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

This comment has been minimized.

Show comment
Hide comment
@cies

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

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

This comment has been minimized.

Show comment
Hide comment
@jwdonahue

jwdonahue Dec 7, 2017

Contributor

@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.

Contributor

jwdonahue commented 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.

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