On 29 September 2011 12:25, David Bosschaert <[email protected]> wrote: > On 29 September 2011 11:58, Jeremy Hughes <[email protected]> wrote: [snip] >> >> I think it's on a package level, not a technology level. >> >> To quote the white paper (executive summary): >> >> "A package can contain an API. There are two types of clients for >> these API packages: API consumers and API >> implementation providers. A change in the second (minor) part of the >> version signals that the change is >> backward compatible with consumers of the API package but not with the >> providers of that API. That is, >> when the API package goes from version 1.5 to 1.6 it is no longer >> compatible with a provider of that API but >> consumers of that API are backward compatible with that API package." >> >> An implementer of BlueprintListener is an API implementation provider. >> A single class can be an API implementation provider of >> BlueprintListener while being an API consumer of other blueprint >> packages. I don't believe the whitepaper describes the subtlety you >> allude to. Have I missed something? > > And again, I may have missed something here too :) The situation that > I'm describing here is that *within* a single package (e.g. the > org.osgi.service.blueprint.container package to stay with our example) > one could be a consumer while still implementing an API provided by > that package. > > That's why when in our example when > org.osgi.service.blueprint.container.BlueprintContainer gets a new > method only the minor version of the package needs to be increased (as > consumers don't implement this interface) but when > org.osgi.service.blueprint.container.BlueprintListener gets a new > method the major version of the package needs to be increased as > consumers do implement this interface, but given they're a consumer > should be allowed to specify a version range like [1.0.0, 2.0.0).
I see what you mean and the whitepaper discusses this scenario in the 4th para of p8: "An interesting problem for exporters is the policy applied to interfaces that are implemented by the consumers of the API. For example, in the OSGi framework, the Bundle Activator interface is not implemented by a framework provider but by consumers of the framework API: bundles. A change in such an interface will not be backward compatible with any consumers of the API and therefore requires a change in the major part of the version. API designers must therefore be acutely aware of the usage pattern of their interfaces and try to prevent making changes to interfaces that are implemented by the consumers of the API. Any change in an interface that is implemented by a consumer of the API breaks backward compatibility for all consumers." Oddly, this conflicts with the 2nd para of p8: "Tools will be able to detect syntactic violations of the semantic versioning by comparing a previous version and the new version." A tool cannot determine whether an interface in an exported package is being exported for consumers or for implementers. There's no standard way of doing so. Moreover, if there was, it wouldn't be enforceable at compile time without changes to the compiler. A tool doesn't have visibility to all the possible importers of the package. It therefore cannot say whether a package is being used by consumers or implementers ... or both!! IMHO the whitepaper attempts to protect consumers too vigorously. A better arrangement would be for the exporter to modify the minor or major version based on changes to the interface(s) in the package rather than what an importer might decide what to do with it. (since I already mentioned declaring what an importer can / cannot do with it is unenforceable). There's nothing wrong with consumers being mindful of what packages they import for interfaces they wish to implement and set their import version ranges appropriately. So: a) the white paper is in conflict with itself para 2 vs 4 on p8 b) what is proposed in para 4 cannot be implemented by tools, so will be ignored by tools providers and will eventually fall by the wayside I guess now, I'm posting to the wrong list as this should be a discussion with the paper's authors ;-) > > Cheers, > > David >
