Open FilipMalczak opened 6 years ago
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.
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?
Another one: are there any restrictions on what happens when major version changes?
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 likeisValidStateChange(...)
andvalidStatesFrom(...)
).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.