mirror of
https://github.com/semver/semver.git
synced 2026-07-11 08:02:23 -05:00
[GH-ISSUE #467] SemVer.org should begin educating people about SPI compatibility #2074
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#2074
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 @derekm on GitHub (Oct 8, 2018).
Original GitHub issue: https://github.com/semver/semver/issues/467
SemVer.org ignores older, more mature technical whitepapers on Semantic Versioning that cover the differences between API consumers & API providers.
In these more mature service-oriented systems, APIs are provided by providers, and APIs are consumed by consumers.
Major numbers indicate breaking changes for API consumers.
Minor numbers indicate breaking changes for API providers.
Patch or Micro numbers indicate backwards compatibility on both the consumer and provider sides.
It would be nice if SemVer.org could begin to raise visibility about this more rigorous approach to pluggable development out of which Semantic Versioning originated.
Shout out to OSGi here: https://www.osgi.org/wp-content/uploads/SemanticVersioning.pdf
@jwdonahue commented on GitHub (Oct 8, 2018):
@derekm, thanks for the awareness. I wonder if you wouldn't be interested in getting involved over at the VersionSchema project. See also versionmeta.org and versionmeta.org.
I was just working on collecting all of the "semver should version X" or "how to apply semver to my non-API Y" kinds of threads that might eventually lead to changes/clarifications in the specs use of "API" and "Package", when I noticed your post. I think we have to be very careful about exactly what it is we're versioning, then we should solve the syntax/semantics for that specific thing.
The fact that breaking changes of any kind are indicated by the minor version field, in your example, implies this approach is not consistent with the semver spec in its current form. Such a change in the spec would be a breaking change. I think his is just one small corner of the dependency graph problem that semver was definitely not designed to solve. Semver provides a version label and simple semantics for a node in the graph, nothing more. The interface/implementation relationships, are just a sub-graph of the larger project yes?
@jwdonahue commented on GitHub (Oct 8, 2018):
On further reflection, adding an interface to an API without providing an implementation is effectively a breaking change! I have to ponder that for a while...
@derekm commented on GitHub (Oct 8, 2018):
E.g., adding methods to an interface is a breaking change to an API provider (because that provider must now implement those new methods), but it is not a breaking change to an API consumer (because that consumer can remain ignorant of those new methods).
Since more rigorous approaches to Semantic Versioning predate SemVer.org, I think this fact above has led to the "simpler" interpretation of "additive changes is a minor version" because those same additive changes are breaking changes for implementors of an interface (unless the additions have default implementations in more recent versions of Java).
Pages 4 and 5 of the original OSGi Sem Ver spec covers this with a toy example.
@derekm commented on GitHub (Oct 8, 2018):
Think of a DAO (data access object) layer that has competing implementations for various backends: SQL, REST, MongoDB, etc. The DAO interface is the SPI. Service layer components that talk to the DAO layer are API consumers. DAO implementations that implement the interface are API providers.
More advanced module systems like OSGi allow different deployments to pick different DAO interface impls that your service will be provided. One deployment might talk to an on-prem SQL database, another deployment might talk to a remote REST service, etc. In these situations, 1.x consumers will work with all of 1.x (for the feature set that that consumer cares about), but a 1.3 provider will not work on a 1.4 system until that provider provides everything added in 1.4.
Hope this helps clarify things!
@jwdonahue commented on GitHub (Oct 8, 2018):
Yes. We basically have a product that has two classes of consumers to which we must communicate different facts. It seems obvious to me that an interface would require different semantics than a collection of interfaces and implementations.
I read the document you referenced. Not sure I like the model. As I see it, an implementation can't be broken by a new interface publication unless it takes a dependency on that new interface. An implementer should never do this in a production environment. I think that one can assume that any interface changes break implementers builds, possibly in undetectable ways. Taking on support for a new interface requires engineering time. A production system that allows a consumer access an a non-compliant implementation through any interface is broken by design anyway.
I am just not convinced the scheme works, much less buys you anything over the current semver spec.
@derekm commented on GitHub (Oct 9, 2018):
Yes, but taking a dependency on that new interface is the whole point! We're talking about upgrades, after all, and about which ones can be applied where without maintenance!
@derekm commented on GitHub (Oct 9, 2018):
@jwdonahue -- something to consider for your VersionSchema project: https://www.infoq.com/news/2012/04/osgi-snapshot
@jwdonahue commented on GitHub (Oct 9, 2018):
Please define exactly what you mean by "interface".
@jwdonahue commented on GitHub (Oct 9, 2018):
Reference #468 for tracking.
@derekm commented on GitHub (Oct 9, 2018):
"Interface" could mean literally a Java "interface." Java is perhaps the one ecosystem with the most mature understanding of the API/SPI divide, whether we're talking JSR libraries (many of which have SPI layers) or OSGi libraries (all of which have SPI layers).
"Interface" could also mean literally any specification. For example, consider the MicroProfile specifications. An implementation of MicroProfile 1.1 is broken with respect to the MicroProfile 1.2 spec until it brings itself into compliance.
We could also think of "interface" meaning "Swagger document." If the Swagger spec is evolving over time and others are separately implementing that spec, then implementers are broken against successive versions until they comply with those versions. (E.g., a 1.4 client can't reliably point to a 1.3 server, especially if that client uses the entire 1.4 surface area.)
@jwdonahue commented on GitHub (Oct 10, 2018):
Is it even possible to make a non-breaking interface change from the perspective of the implementers?
@jwdonahue commented on GitHub (Oct 10, 2018):
Current semver:
Consumer claims dependency on
1.*.*of Interface.Implementer claims dependency on
1.0.*of Interface.Semver is oriented to telegraphing breaking, non-breaking interface addition, other non-breaking change. Implementations are always broken by additions to interfaces. Semver is oriented to versioning collections of artifacts that contain at least one interface and usually one or more implementation artifacts.
OSGi semantic versioning:
Consumer claims dependency on
1.*.*of Interface.Implementer claims dependency on
1.0.*of Interface.OSGi is oriented to telegraphing consumer breaking, implementer breaking, non-breaking change. Implementations are always broken by additions to interfaces.
The definition of the semantic meanings of the version strings are subtly different, but I don't see any change in how consumers and implementers declare their interface dependencies. What am I missing?
@jwdonahue commented on GitHub (Oct 11, 2018):
@derekm, I've got a catch-all for these "what are we versioning" issues. I posted your link to the OSGi semantic versioning doc and the two threads are already cross-linked with each other.
Unless you intend to issue a PR on this, please contribute to #468 and close this issue at your earliest possible convenience.
@derekm commented on GitHub (Oct 11, 2018):
@jwdonahue -- Regarding your comment above about equivalencies: yes, I agree, my point was exactly that the equivalency is already pre-existing. But as you suggest the orientation of the perspective is different, or as I see it, there is a void of explicit information where that information is otherwise only implied. I've noticed that with SemVer, people take an explicit "consumers" point of view and can't see the implicit "implementers" point of view, so I thought it might be a matter of education on SemVer's part to begin educating the public in a more explicit manner.
Closing in deference to #468.