Always add a version if exporting a package

[laeubi]

Currently if one exports a package

1. Using a Quickfix
2. Using the Manifest editor

PDE adds the export without a version. Unversioned packages have the drawback that one can not reliable reference them with a proper import range (what recently was added to PDE: https://github.com/eclipse-pde/eclipse.pde/pull/1007 and enhanced with https://github.com/eclipse-pde/eclipse.pde/pull/1212).

I therefore would suggest that PDE exports packages by default with version 1.0.0 (what is also the default version for Bundles created by PDE). In the rare cases where the user actively choose to not using a version, it can then be edited manually.

[merks]

Versioned packages are a good thing. That being said, does PDE, or anything else, help maintain an up-to-date version as APIs in that package change? At least for bundle versions, there are the API tools. In the end, a versioned package is only as useful as the accuracy of the version...

[laeubi]

Sadly API-Tools currently does not, but if we start more using packages (what already is done!) it might be good to enhance. Beside that Tycho offers tycho-baseline:verify mojo that supports OSGi semantics for package (and bundle) versions, e.g. m2e is using it.

Beside that, no version is as bad as a default version that never increments, so it is not really making the situation worse to use one.

[merks]

Beside that, no version is as bad as a default version that never increments, so it is not really making the situation worse to use one.

One cannot specify a version constraint on a unversioned package can one? It seems to me that an arbitrary version on a package that's not properly maintained will create a false illusion (for the consumer) that a unversioned package does not create. So I hope not to see this show up in Platform projects (but I bet it will) unless something is done to properly maintain the versions.

None of this is arguing that we should not do this is PDE, it's a word of caution to those who version their packages that they are obligated to maintain those version properly. Also, perhaps as those who encourage properly maintained version, we should consider how best to ensure that both are supported by our tools.

[laeubi]

One cannot specify a version constraint on a unversioned package can one?

Correct.

It seems to me that an arbitrary version on a package that's not properly maintained will create a false illusion

Without an version it can't be maintained at all :-)

So I hope not to see this show up in Platform projects (but I bet it will) unless something is done to properly maintain the versions.

Currently we have a wild mixture of things, at least in Equinox we try to manually maintain the versioned exports, anyways even if there are problems they can be fixed, so there is always two sides, the importers that need to maintain proper import ranges and the exporters that need to follow the semantic versioning.

I just see no other way out than starting with something simple e.g. let PDE suggest by default that packages should have a version.

[HannesWell]

It seems to me that an arbitrary version on a package that's not properly maintained will create a false illusion

Without an version it can't be maintained at all :-)

That's right. But on the other hand a not maintained package version is actually as good as no package version.

I just see no other way out than starting with something simple e.g. let PDE suggest by default that packages should have a version.

Starting simple is for sure valid, but I think if PDE just suggests to add versions without providing any support to properly maintain them, I see only really small to no value in changing that.

What would be really really helpful is if API-Tools would consider packages as well. If that would work, suggesting package version would be very valuable too. Without being familiar with the details, I assume that it shouldn't be that hard, because the same rules that apply for the bundle version also apply for the package version. So it would be more or less additional versions to understand and smaller units to check. Respectively if API-tools detects that a change requires a new minor or major version it has to suggest the same change for the version of the containing package too, not only for the bundle version.

[laeubi]

That's right. But on the other hand a not maintained package version is actually as good as no package version.

It is not, if there is no export, then importers can't use a version at all (managed or not does not matter), so if one introduce a version later on, all consumers have to adapt ...

Starting simple is for sure valid, but I think if PDE just suggests to add versions without providing any support to properly maintain them, I see only really small to no value in changing that.

To be honest I won't recommend anyone to use API tools anyways, as mentioned for those who really care about API there are better tools like the tycho/bnd baseline that really checks for semantic versioning.

In any case please keep in mind this important part of the request:

in the rare cases where the user actively choose to not using a version, it can then be edited manually.

I have not seen any recent package export additions in platform, but even if one feels uncomfortable with that it can be changed to not using a version.

Respectively if API-tools detects that a change requires a new minor or major version it has to suggest the same change for the version of the containing package too, not only for the bundle version.

Package and bundle versions are not related and that's the biggest strength, so suggesting to change the package version the same way as the bundle version would actually be very bad.

[EverettHanke]

I'll happily begin working on this.

[HannesWell]

That's right. But on the other hand a not maintained package version is actually as good as no package version.

It is not, if there is no export, then importers can't use a version at all (managed or not does not matter), so if one introduce a version later on, all consumers have to adapt ...

But you can still import a package without any version(-range) even if it has a version?!

Respectively if API-tools detects that a change requires a new minor or major version it has to suggest the same change for the version of the containing package too, not only for the bundle version.

Package and bundle versions are not related and that's the biggest strength, so suggesting to change the package version the same way as the bundle version would actually be very bad.

That's not what I meant. I just wanted to say that the same mechanism can be used to detect the changes, of course it then has to be put into the context of a package and not entire bundle and the required version bump has to consider that. But I think implementing the latter rule is the simpler part.

I'll happily begin working on this.

Thanks for your interest, but since the discussion about this feature has not yet settled and there is no agreement on the prerequisites respectively they are not yet implemented, it might be a bit early to start this. Respectively if you still want to start this, it might take longer than usual to accept a corresponding PR.

[laeubi]

But you can still import a package without any version(-range) even if it has a version?!

Exactly but you have the choice and then you should be aware about the consequences, the default for PDE now is to add a versionrange so that's already a good default.

On the other hand you still has the choice to not export a version and then you should be aware of the consequences. So PDE should use that as a good default.

So I'm quite confused why it is such a big deal to having good defaults just to support a bad style/tooling of platform that even is rarely used (New exported packages are that rare I can't remember any from the top of my head).

[merks]

To repeat myself

It seems to me that an arbitrary version on a package that's not properly maintained will create a false illusion (for the consumer) that an unversioned package does not create.

Stated differently, a poorly maintained or unmaintained package version is worse than no package version and is therefore is arguably a worse default until tools are provided to help maintain packages version as the package API evolves.

This is not an argument about whether versioned packages are better than unversioned packages. I think we can all agree it would be better that packages have versions and that package imports be used. So no need to belabor that point. But please try to understand the "big deal" about unmaintained versions.

[laeubi]

Just because for platform it implies everyone "poorly maintains packages", that does not mean other don't do the same.

Also no version does not imply anything either, neither "good" or "bad" maintenance... And in fact the situation is completely the same (for the consumer) about bundle versions as these are already not "properly maintained" (e.g. do not follow semantic versioning) by platform and the tooling does not complain about invalid lower bounds interestingly this seems to be not a reason to require bundles without a version or use the default 0.0.0 version for bundles.

So still this all sounds a bit splitting hairs to me to argue against something that do not harm anything but would help to make people adopt best practices, especially as I won't recommend anyone to use API tools at all, there are better tooling and people do use that so support for that is nothing mandatory here.

[merks]

We're probably going in a circle.

If there are no tools to help follow best practices, i.e., to maintain and manage meaningful semantic versions of bundles and packages, then the best practices are only best in principle with no effectively way to apply those principles going forward. To reject API tools (because, yes they are hard to maintain and hard use) effectively rejects the only way to manage the best practices for any reasonably complex project without providing any alternative. So we argue that when someone creates a new bundle and/or exports a package, we do that all with version 1.0.0 because that's the best practice. Indeed it is. After that though, as a tool provider, we are done with the consumer and we tell them, don't use the API tools that we provide because they suck, use your personal brain to manage versions properly. Unfortunately the human brain doesn't scale arbitrarily, so we shouldn't be surprised that the consumer thinks that we personally suck, not just that the tools suck.

We do have tools that maintain the semantic version of bundles but we do not have tools to maintain the semantic versions of packages. Hence there is a difference.

[laeubi]

We do have tools that maintain the semantic version of bundles but we do not have tools to maintain the semantic versions of packages. Hence there is a difference.

I have posted "the tool" in my second comment, different people use different tools.

We're probably going in a circle.

I really feel blushed to having wasted so much time trying to make PDE adapt to OSGi best practice with a trivial non disruptive an optional enhancement request.

So instead of improving one little thing (that might be then driving people to improve other things) now we simply do .. nothing at all. That's really frustrating .

[HannesWell]

We're probably going in a circle.

I really feel blushed to having wasted so much time trying to make PDE adapt to OSGi best practice with a trivial non disruptive an optional enhancement request.

So instead of improving one little thing (that might be then driving people to improve other things) now we simply do .. nothing at all. That's really frustrating .

It was never said that we do nothing. The discussion was only about the prerequisites for this change. I think we all agree that this change, if the mentioned prerequisites, is very valuable. So there is no need to close this. And the reason for the required better tool support is less a technical one and more a psychological one. And since you mentioned that different people use different tools: That's totally right, but that also means that those that are not just relying on the tycho-baseline plugin respectively bnd-baseline and use the PDE API-tools would still lack tool-support.

But we should indeed put our energy on working on the prerequisites and everything will be good in respect to this issue. In fact I'm interested in working on the suggested prerequisite if time permits it, but if somebody else is also interested in that: everyone is welcome to work on that too. :)