Add an equinox.api bundle

[laeubi]

Currently we have usually have bundles that are mixed with API and
implementation, even worse those also consists of split packages, most
notable the 'org.eclipse.core.runtime' package that makes it hard to use
the API independent from the implementation and to not break existing
usages it is not easily possible to improve the situation because of the
widely use of require bundle in eclipse. Also we do not even have good
API check support for exported packages and split-packages in general
what has caused problems in the past.

This now tries to improve the situation in the following way:

• add a new equinox.api bundle that host the actual API
• require-bundle it on the old places with reexport to ensure backward
  compatibility
• add tycho-baseline-mojo to check for package version consistency
  according to semantic-versioning

As a result, previous consumers of org.eclipse.equinox.common and
org.eclipse.equinox.registry can now safely use import-package instead
allowing for easy replacement of the API if desired.

[github-actions]

Test Results

0 files   -   663  0 suites   - 663   0s ⏱️ - 1h 17m 23s
0 tests  - 2 209  0 ✅  - 2 161  0 💤  -  47  0 ❌  - 1 
0 runs   - 6 771  0 ✅  - 6 627  0 💤  - 143  0 ❌  - 1 

Results for commit cb35d63. ± Comparison against base commit caf78f7.

[vogella]

A bold move and a great one. Would also be nice to have a way to deprecate the usage of the old export, so that users see that they should adjust there dependencies.

[merks]

Yes another bundle export this package split package.

I assume some attributes will be needed. I'm not sure if other importers will need to change?

[laeubi]

I assume some attributes will be needed. I'm not sure if other importers will need to change?

No the goal is to have one package without mandatory attributes so users that want to reference the new api exported package do not need to specify anything and old users (that use an attribute) get the one as before.

Actually we then can replace all these special imports with regular ones.

[tjwatson]

I don't see how this approach achieves the goals. Is the goal have a single bundle that exports all the parts of org.eclipse.core.runtime? If so then don't you need all the stuff from the legacy org.eclipse.core.runtime bundle also? You now will have two exporters of org.eclipse.core.runtime with no mandatory directives. That makes it very much unsafe to do import package on org.eclipse.core.runtime because you will not know which version you will get wired to.

If we want to do this then I suggest moving all the parts of the org.eclipse.core.runtime to platform (org.eclipse.equinox.common, org.eclipose.equinox.registry). Then put ALL the API from org.eclipse.core.runtime into some "API" bundle and then have all the various bundles do the requires on that.

But that all seems very much an academic exercise that I see not solving any real problem (much like the original notion of splitting org.eclipse.core.runtime into smaller "parts"). I think all would be much more maintainable if we simply moved all the parts (including the API) back to the org.eclipse.core.runtime bundle. I don't see any advantage in separating the API from the bundle here because we don't have any real usecases where we want a different implementation of the API than we provide by this project.

We would still need to provide the "parts" bundles like equinox.common and equinox.registry, but they would be shell bundles that simply require the core.runtime bundle and export the facade "part" of the org.eclipse.core.runtime bundle.

[laeubi]

I don't see how this approach achieves the goals. Is the goal have a single bundle that exports all the parts of org.eclipse.core.runtime? If so then don't you need all the stuff from the legacy org.eclipse.core.runtime bundle also?

Yes in the end there should only be one org.eclipse.core.runtime package

I think all would be much more maintainable if we simply moved all the parts (including the API) back to the org.eclipse.core.runtime bundle.

In general yes, but I don't see how it would be possible to break exiting users that e.g. currently require-bundle equinox-common. Therefore my idea was to create a new bundle.

I don't see any advantage in separating the API from the bundle here because we don't have any real usecases where we want a different implementation of the API than we provide by this project.

The problem is more that the implementation have very specific structure and especially the

Require-Bundle: org.eclipse.osgi;bundle-version="[3.18.0,4.0.0)";visibility:=reexport

is something that really make things worse, so I don't see how to make this ever go away an have a "clean" org.eclipse.core.runtime bundle.

And as the package contains some very basic interfaces (e.g. IProgressMonitor and/or CoreException) this is pulled in almost everywhere. And this is for example also mentioned here that people like to substitute the real bundle/api:

• replaced Require-Bundle with Import Packages #253