apiguardian-team / apiguardian

@API Guardian
https://apiguardian-team.github.io/apiguardian/docs/current/api/
Apache License 2.0
187 stars 23 forks source link

Introduce SPI status to indicate the extension points #11

Open armiol opened 6 years ago

armiol commented 6 years ago

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.

eliasvasylenko commented 4 years ago

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.