apiguardian icon indicating copy to clipboard operation
apiguardian copied to clipboard

Introduce SPI status to indicate the extension points

Open armiol opened this issue 6 years ago • 1 comments

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.

armiol avatar May 14 '18 12:05 armiol

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.

eliasvasylenko avatar Nov 14 '19 15:11 eliasvasylenko