Add bnd baseline plugin

[Emily-Jiang]

Fixes #406

Signed-off-by: Emily Jiang emijiang6@googlemail.com

[Emily-Jiang]

The tool spotted a major change. What changes have you made since the last release?

[arthurdm]

thanks for the PR @Emily-Jiang

Is there some more information on this tool, such as how it is run, what it checks for, etc? Would be good to add that information into this repo via this PR. I don't personally know much about this tool, so I was thinking the same thing as @EricWittmann in terms of versions being different in a few packages.

Should the next release just make it 2.0 across the board? I am thinking about the scenario where multiple version of MicroProfile are loaded into a particular implementation and you get mixed packages from different MP OpenAPI versions, etc. Maybe not an issue, just something that came to mind.

[jmini]

Should the next release just make it 2.0 across the board?

+1

---

I really think that it is a really good idea to start to add tool to detect breaking changes. OSGi tooling is in this business since years and close to the Eclipse community so this is a good choice. The only alternative that I know is https://revapi.org/

The way OSGi can defines and use version at package level is not common in the rest of the Java world. In OSGi you can tell:

I have a dependency on a bundle that provides this package in this version range

And then the tooling is capable of finding the dependency that match this constraint.

In the rest of the Java world (when you do maven or gradle driven builds), you define your dependency using the Maven coordinates system: groupId:artifactId:version. The version is the version of the jar (or library / artifact, call it the way you prefer).

This is why I think we should put the version in the Annotation to be the same as the one in the spec, meaning at in the pom ("2.0" everywhere on the master branch, and "1.2" on the 1.x branch). And this should be updated as part of the version bump process. So that when our pom says we are one version a.b.c-SNAPSHOT the annotation is @org.osgi.annotation.versioning.Version("a.b").

If somebody make a change that is breaking (remove a method after we have published version 2.0) the tool should detect that the package should be at version 3.0 and in this case it should break the build.

We are doing pom/maven driven versioning and not package based versioning as OSGi is doing it.

[jmini]

I have posted a message in the Eclipse MicroProfile Google Group to get some feedback about usage of the bnd-baseline-maven-plugin in MicroProfile projects: https://groups.google.com/g/microprofile/c/dzYrVG3g9XU

[jmini]

Build of commit 89aff6a is failing with this output:

12:03:21 [ERROR] Baseline mismatch for package org.eclipse.microprofile.openapi.annotations.parameters, MINOR change. Current is 1.0.1, repo is 1.0.0, suggest 1.1.0 or -
12:03:21 [ERROR] Baseline mismatch for package org.eclipse.microprofile.openapi.annotations.responses, MINOR change. Current is 1.0.0, repo is 1.0.0, suggest 1.1.0 or -
12:03:22 [INFO] ------------------------------------------------------------------------
12:03:22 [INFO] Reactor Summary for MicroProfile OpenAPI 2.0-SNAPSHOT:
12:03:22 [INFO] 
12:03:22 [INFO] MicroProfile OpenAPI ............................... SUCCESS [  9.276 s]
12:03:22 [INFO] MicroProfile OpenAPI API ........................... FAILURE [ 17.238 s]
12:03:22 [INFO] MicroProfile OpenAPI TCK ........................... SKIPPED
12:03:22 [INFO] MicroProfile OpenAPI Specification ................. SKIPPED
12:03:22 [INFO] MicroProfile OpenAPI SPI ........................... SKIPPED
12:03:22 [INFO] ------------------------------------------------------------------------
12:03:22 [INFO] BUILD FAILURE
12:03:22 [INFO] ------------------------------------------------------------------------
12:03:22 [INFO] Total time:  28.771 s
12:03:22 [INFO] Finished at: 2020-07-02T10:03:22Z
12:03:22 [INFO] ------------------------------------------------------------------------
12:03:22 Waiting for Jenkins to finish collecting data
12:03:22 [ERROR] Failed to execute goal biz.aQute.bnd:bnd-baseline-maven-plugin:4.3.0:baseline (baseline) on project microprofile-openapi-api: An error occurred while calculating the baseline: The baselining plugin detected versioning errors -> [Help 1]
12:03:22 [ERROR] 
12:03:22 [ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
12:03:22 [ERROR] Re-run Maven using the -X switch to enable full debug logging.
12:03:22 [ERROR] 
12:03:22 [ERROR] For more information about the errors and possible solutions, please read the following articles:
12:03:22 [ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException
12:03:22 [ERROR] 
12:03:22 [ERROR] After correcting the problems, you can resume the build with the command
12:03:22 [ERROR]   mvn <goals> -rf :microprofile-openapi-api

Source https://ci.eclipse.org/microprofile/job/Open-API-pull-requests/55/console

---

I have merged master into this PR and I have fixed the value in the @org.osgi.annotation.versioning.Version as suggested by the maven build.

[jmini]

I am now waiting for some feedback in the Google Group before this PR can be merged.

[Emily-Jiang]

I've replied via the ML. Feel free to ask questions here if you have any further comments! Here has more explaination regarding package version. More info...

[jmini]

From @EricWittmann :

Why was @org.osgi.annotation.versioning.Version changed to 2.0 in some spots but not others?

The tool work per packages (this is an OSGi construct). And the MicroProfile way of doing versioning seems to be at package level, as explained by @Emily-Jiang on the Mailing List:

Some of the packages are remained unchanged, so the package version stays at 1.0. In this case, the end users will know the api they use are the same as the one in the new jar.

---

From @arthurdm :

Should the next release just make it 2.0 across the board?

Same answer as previously. This could be a valid approach, but I think it is better to do the same as all MicroProfile projects.

---

From @Emily-Jiang :

The tool spotted a major change. What changes have you made since the last release?

Yes this is known and tracked in this issue https://github.com/eclipse/microprofile-open-api/issues/251. So it is a good sign that the tool spotted the same breaking change again and bumped the version to 2.0 in the corresponding packages.