Well defined API status graph

[FilipMalczak]

Status quo is that the statuses (huh, accidental wordplay, nice) are only described with javadocs. Missing part is some formal definition of state graph.

This API is only documentational unless there will be some tools provided that would check whether annotated elements behave as expected between versions. It can be quite easy to misinterpret the javadoc in some minor detail and that would result with different tools behaving differently (one could consider some API change as valid, another one could raise a warning in the same case). There should be strict definiton of rules that would be later shared by these tools.

The graph

See the picture for proposed graph, suited for 1.0.0 of apiguardian API.

An issue to be discussed: can STABLE go to MAINTAINED?

I'd say that it shouldn't. IMO STABLE should mean that API element in that state will stay for the end of major version lifecycle.

Another one: are there any restrictions on what happens when major version changes?

Again, I'd say that there shouldn't be. Change of major version defines basically a new API that may or may not look similiar to the previous one.

The module

There is a pull request #3 that splits the repo to several modules. I would propose adding yet another module apiguardian-contract that would contain some simple graph model (that would have domain names, so e.g. ApiElementState instead of Node and StateTransitionRule instead of Edge) and an utility class with static content that would provide set of rules describing the graph that was agreed upon and some ways to inspect it (methods like isValidStateChange(...) and validStatesFrom(...)).

There is WIP pull request #8 for my implementation draft.

Providing such module would make it easier for creators of tools to keep their behaviour consistent with different tools.

[marcphilipp]

I think a graph is a good idea!

An issue to be discussed: can STABLE go to MAINTAINED?

Only when the major version changes.

Another one: are there any restrictions on what happens when major version changes?

Nope.