apiguardian
apiguardian copied to clipboard
Introduce SPI status to indicate the extension points
The current set of Status
values looks consistent for most of projects. However, in a framework or library — which are intended to be used as building blocks — there is also often an additional need to indicate the designed extension points.
SPI
status solves such a task by taking "it is safe to use" semantic (i.e. STABLE
) and appending it with "you are welcome to extend this element" — as per SPI definition.
Some libraries dedicate a package to this purpose. However, package-based approach isn't always possible and it's way less convenient for tasks such as code inspection/post-processing.
In a way, this issue is similar to #9, but instead of restricting the API extension, I'd propose to mark the elements that are designed for it.
I think this should be considered orthogonal to the current status options; an interface can be intended to be implemented by the API consumer while at the same time be e.g. experimental or deprecated. So a separate boolean element on the annotation to indicate this may be more appropriate.
But I second that this distinction can be important, for instance to help automated baseline checkers properly understand backwards-compatibility. Adding methods to a normal API interface is a minor bump according to semantic versioning, but adding methods to an SPI interface is a major version bump.