Introduce INCUBATING status

[FilipMalczak]

I'm missing API status that would mean "this is completely new feature and it will almost definitely change - expect SOME solution to problem solved by this, but don't get too attached to current form".

That way EXPERIMENTAL would mean something like "this API may morph, but gradually", while INCUBATING would mean "we have no clue how to describe this domain/context, but here's an approach".

I wouldn't provide any contract on what happens to such features in future versions, but I'd say that INCUBATING features shouldn't be promoted directly to MAINTAINED or STABLE and should go through EXPERIMENTAL stage first.

In the end, EXPERIMENTAL would mean "we're polishing this", while INCUBATING would mean "we're coming up with this".

[marcphilipp]

I'd find it very hard to distinguish between experimental and incubating. Thus, I'd say "experimental" is sufficient.

@sbrannen @sormuras @mmerdes @bechte Thoughts?

[sbrannen]

I think experimental suffices for such use cases as well.

Ultimately, we do not want to condone a proliferation of enum constants.

[FilipMalczak]

How about a common extension interface, that would allow to add some metadata API declaration. This could be an additional entry point for external tools that would like to work with API-Guardian.

[sbrannen]

I don't understand what you are proposing with a "common extension interface".

@API is an annotation. Thus there is no way to add an interface to that.

If you mean something else, please expound.

[FilipMalczak]

The most primitive extension interface would be tagging:

@interface API {

    /** (...) */
    Status status();

    /** (...) */
    String since() default "";

    /** (...) */
    String[] consumers() default "*";

    /** (...) */
    String[] tags() default {};
/* (...) */
}

Those tags would not change any semantics in scope of this project, but could be used by external tools to customize their behaviour, e.g. @API(status = EXPERIMENTAL, tags="incubating").

Another approach would be attributes:

@interface Attribute{
    String name();
    String value();
}

@interface API {
    /* (...) */
   @Attribute[] attributes() default {};
}

with usage

@API(status = EXPERIMENTAL, attributes = { @Attribute(name = "substatus", value = "INCUBATING") }

I may have screwed up the syntax of annotation-as-value, but you get the gist.

I don't like neither of these approaches, to be honest...

I'm not sure whether that should be handled on level of this API, or extensions like that should be handled via tool-specific annotations.

Common interface would make it more managable and provide better tool interoperability, but at this moment it is hard to think of all the possible use cases and we may find ourselves in a situation where such extension entry point will be insufficient for some tool.