Create and communicate policy for published API lifecycle

[jlink]

SUGGESTION:

Introduce annotation for all interfaces and classes supposed to be used from outside:

@PublicAPI(Stable)
@PublicAPI(Maintained)
@PublicAPI(Experimental)
@PublicAPI(Deprecated)
@PublicAPI(Internal)

• Stable: Will be here forever (in this major version 5.x)
• Maintained: Considered mostly stable. If considered for removal, it will be deprecated for at least one minor version.
• Experimental: Use at your own risk. Might be removed at any time.
• Internal: Only used for public members in types that have a @PublicAPI annotation.

Everything not annotated would be considered for internal use only.
Annotation would allow to produce API change reports for all releases.

Tasks

• Create annotation
• Add paragraph about API annotations to documentation
• Annotate junit-launcher
• Annotate junit-commons
• Annotate junit-console
• Annotate junit-engine-api
• Annotate junit5-api
• Annotate junit5-engine
• Annotate junit4-engine
• Annotate junit4-runner

[mmerdes]

Interesting idea.

Wasn't experimental considered harmful in Junit4?

Cheers,
Matthias

Johannes Link notifications@github.com schrieb am Sa., 12. Dez. 2015 um
11:15:

SUGGESTION:
Introduce annotation for all interfaces and classes supposed to be used
from outside:

@publicapi(Stable)
@publicapi(Maintained)
@publicapi(Experimental)
@publicapi(Deprecated)
@publicapi(Internal)

Stable: Will be here forever (in this major version 5.x)
Maintained: Considered mostly stable. If considered for removal, it will
be deprecated for at least one minor version.
Experimental: Use at your own risk. Might be removed at any time.
Internal: Only used for public members in types that have a @publicapi
https://github.com/PublicAPI annotation.

Everything not annotated would be considered for internal use only.

Annotation wouzld allow to produce API change reports for all releases.

—
Reply to this email directly or view it on GitHub
#63.

[marcphilipp]

Well, one learning from JUnit 4 would be to not use package names (e.g. experimental) for this purpose. Because in case you later decide to promote something from Experimental to Stable you'd have to change the package name.

[marcphilipp]

I like the idea, but not the current wording. IMHO @PublicAPI(Internal) looks a bit strange, doesn't it?

[dsaff]

FYI, the primary problem with "experimental" in JUnit was that we used it as a package name, so:

1. If we wanted to promote something out to fully-supported, you'd have to change the name, which broke everyone's code, so:
2. We ended up leaving mostly-working, mostly-supported stuff in experimental, so:
3. People came to expect that everything in experimental would also be supported, so:
4. experimental as a flag of "don't trust this" became useless.

I think the annotation approach avoids #1, so hopefully it will also avoid the rest.

[bechte]

I also like the idea. if I understand you correctly, you want to annotate all public elements in the API packages that we declare to be the public API. Some methods must be public even though we only want to use them internally which is absolutely fine to have @publicapi(InternalOnly).

I am with Marc that it might need some fine tuning regarding the names, but it's a good and self-documenting solution.

Suggestion: Instead of PublicAPI we could say: APIVisibility or something alike.

We could start with your proposal and leave the renaming for later. :)

[jlink]

I'd only annotate classes that are considered public API. Everything else could automatically be for internal use only.
@publicapi(Internal) would then be needed for public but internal members on otherwise published API types.

But we could also go with annotating every public type. Might be more work, but also be more consistent.

Am 15.12.2015 um 07:29 schrieb Stefan Bechtold notifications@github.com:

I also like the idea. if I understand you correctly, you want to annotate all public elements in the API packages that we declare to be the public API. Some methods must be public even though we only want to use them internally which is absolutely fine to have @publicapi(InternalOnly).

I am with Marc that it might need some fine tuning regarding the names, but it's a good and self-documenting solution.

Suggestion: Instead of PublicAPI we could say: APIVisibility or something alike.

We could start with your proposal and leave the renaming for later. :)

—
Reply to this email directly or view it on GitHub.

[schauder]

Don't like the name ApiVisibility. After all the visibility is defined by the Java Language Specification. How about ApiUsage? ApiUsage(internal) sounds about right to me.

Annotations like that would be really nice to have independent of JUnit ... but maybe this becomes obsolete with Project Jigsaw?

[marcphilipp]

I've created a branch with the annotation draft: issue63-api-annotation.

[jlink]

I'd go for the trivial ones if no one minds:

• junit-commons: everything internal
• junit5-engine: everything internal, except JUnit5TestEngine: Experimental
• junit4-engine: everything internal, except JUnit4TestEngine: Experimental
• junit-console: everything internal, except ConsoleRunner.main: Maintained

Any objections?