Make @API public to allow Extensions and TestEngines to adopt API semantics

[smoyer64]

Making @API public allows Extension and TestEngine developers to adopt JUnit 5's API "typing". This also makes the API tools proposed in #144 more useful as they'd be applicable to the other projects.

---

I hereby agree to the terms of the JUnit Contributor License Agreement.

[sbrannen]

Interesting proposal!

We'll consider it for M2.

[volkovs]

@smoyer64 if @API is accepted to be public, should not it be moved from junit-commons to junit-api module? Usage in 3-rd party code will require production code dependency on junit-api, but at least junit-api is lightweight.

P.S. Ideally it should be in separate module/project in future allowing projects still in Java 7 to use it (it might still be true for current annotation location). Separate project might unite very different API tools #144 (including FindBug rules checking for internal API usage and maven plugins as code scanners / release notes builders).

[smoyer64]

@volkovs The junit-jupiter-api module already has a dependency on junit-platform-commons. My initial thought was that I'd like to use @API and it's related tools elsewhere - in which case a completely standalone module would be better. When Java 9 is released, project jigsaw is supposed to take care of hiding internal-only API calls (per JEP 260: Encapsulate Most Internal APIs). Will we get enough tools to replace @API? I have no idea.

[sbrannen]

@volkovs, moving @API to the junit-jupiter-api module is forbidden: various parts of the JUnit Platform use @API, and Platform modules must not have any dependencies on JUnit Jupiter or JUnit Vintage modules.

I agree with @smoyer64: one viable option would be to move @API to its own artifact. The JUnit team has in fact already discussed such a possibility.

[sbrannen]

Team Decision: make Experimental.

[sbrannen]

Would you mind rebasing on master and squashing into a single commit?

[marcphilipp]

We could just squash and merge through GitHub, couldn't we?

[sbrannen]

I'm not sure if that new GitHub squash feature physically rebases on master.

[smoyer64]

I tried to use git commit --squash (but now know I should stick with git rebase). Sorry!

[sbrannen]

I usually do something like this:

> git rebase master
> git rebase --interactive --autosquash HEAD~4

Then I select "f" (for fix) for the last three commits and reword the remaining commit if necessary.

[smoyer64]

Okay ... I'm sticking with my favorite method (for branches) - it's back to a single commit!

git reset master
git add ...
git commit -m "<altered message>"
git push -f

[sbrannen]

Aye aye, captain!

Whatever floats your boat... and gets your commits clean. 😉

[smoyer64]

Someone seems to have noticed my avatar?

[sbrannen]

ummmmmmm

no....

not consciously at least.

But now that you mention it, perhaps that was my subconscious telling me what to type. 😉

[sbrannen]

FYI: this issue is related to #436.