You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Julian Reschke <re...@apache.org> on 2026/09/30 15:35:41 UTC
Bundle versions vs API changes
Hi,
(apologies: written with AI help)
I think it would be useful for Commons Collections to use semantic
versioning for the public packages, rather than using the bundle version
as the package version.
There are two main reasons:
1. The bundle version and package version represent different things
For example, suppose we have:
4.5.0 - existing API
4.6.0 - with backward-compatible API additions
If the exported package version is simply taken from the bundle version,
a consumer compiled against 4.6.0 will by default require:
org.apache.commons.collections4;version="[4.6,5)"
That consumer then cannot run in an OSGi container that only provides
4.5.0 (and yes, that happened for us in Jackrabbit Oak).
This is actually the correct behavior: the consumer may use API which
was introduced in 4.6.0, so resolving it against 4.5.0 could result in
runtime errors such as NoSuchMethodError.
With semantic package versions, the package version reflects the API
compatibility:
major = breaking API change
minor = backward-compatible API addition
micro = backward-compatible bug fix
This gives OSGi the information it needs to resolve package dependencies
based on the API that is actually required.
2. The bundle plugin can help maintain the versions
The OSGi/bundle tooling can detect API changes and suggest the
appropriate package version changes.
That means we do not have to manually determine whether a package change
is a major, minor, or micro change in every release. The tooling can
identify API changes and help enforce the semantic versioning contract.
The important distinction is:
Bundle version: Which Commons Collections release am I using?
Package version: Which version of this particular API am I compatible with?
Using the bundle version as the package version effectively says that
every Commons Collections release creates a new version of every
exported package. That makes OSGi package version ranges unnecessarily
restrictive and mixes product/release versioning with API compatibility.
Using semantic versions for the exported packages gives OSGi a more
useful compatibility contract, while the bundle version can continue to
identify the Commons Collections release.
I can provide a (really small) PR implementing this, including the
necessary OSGi/bundle configuration and versioning changes, if there is
agreement that this is a direction worth pursuing.
Best regards, Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: Bundle versions vs API changes
Posted by "Piotr P. Karwasz" <pk...@apache.org>.
Hi Julian,
Thank you for starting this discussion.
In Apache Log4j we've been using OSGi semantic versioning since version
2.21.0, which is why the Log4j API package (o.a.logging.log4j) has still
version 2.20.2. We use the BND plugins directly, since at that time
Felix was releasing the maven-bundle-plugin very sporadically.
From my experience it does introduce some churn, especially for
contributors that unnecessarily introduce new public methods, but the is
not necessarily bad, since the maintainers can easily spot them from a
build failure and ask the contributor to make the method private.
We created a small guide for contributors, so bumping a package version
is not a problem any more:
https://logging.apache.org/logging-parent/troubleshooting.html#bnd-baseline
What is still confusing, even for maintainers, is bumping the version by
the right amount or reverting the bump after a change was rolled back or
cherry-picked to an older branch.
We do *not* always follow the *minimal* version bumps: when we introduce
a new public API we bump the version of the package to the version of
the artifact, *not* the minimum required. This spares us the headache of
wondering, whether version 4.21.0 of the package was introduced in
version 4.45.0 or 4.46.0 of the artifact.
When we introduced this in Log4j, there wasn't any tooling that
protected us from *unnecessary* version bumps.
On 1.10.2026 10:58, Julian Reschke wrote:
> You'll get warnings like
>
> [WARNING] org.apache.commons.collections4.bag: Excessive version
> increase; detected 4.6.1, suggested 4.6.0
>
> because the export version needlessly changed.
I'll check this out, since it might be interesting, although, as I
mentioned above for minor version bumps I find bumping the version to
the version of the artifact less confusing.
Piotr
[1]
https://logging.apache.org/log4j/2.x/release-notes.html#release-notes-2-21-0
[2]
https://logging.apache.org/logging-parent/troubleshooting.html#bnd-baseline
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: Bundle versions vs API changes
Posted by Julian Reschke <re...@apache.org>.
...actually, running:
mvn bundle:baseline -DcomparisonVersion=4.4
reports
[ERROR] org.apache.commons.collections4.functors: Version increase
required; detected 4.6.1.SNAPSHOT, suggested 5.0.0
which (I believe) is caused by commons-collection's Predicate now
implementing JDK Predicate.
The bundle plugin considers this a breaking change, even with a default
implementation. AFAIK, this is because it would break code that already
has "test(...)".
Yes, that's picky, but could be overridden.
Best regards, Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: Bundle versions vs API changes
Posted by Julian Reschke <re...@apache.org>.
Am 30.09.2026 um 22:31 schrieb Julian Reschke:
> Am 30.09.2026 um 21:05 schrieb Gary Gregory:
>> Hi.
>>
>> Unless the plug in figures out what's what by itself on a per package
>
> It does.
>
>> basis, this will be unmaintanable IMO. I don't see the point of this
>> anyway
>> since we publish a JAR file, not packages.
> The JAR files contains packages, no?
>
> OSGi allows you to restrict what other components see (can use), and it
> also declares which other packages (versions) it needs. That's useful
> when using generic stuff like other commons components or maybe SLF4J
> etc. All that goes into MANIFEST.MF.
>
> (and yes, there likely are other approaches, but OSGi is what I know)
>
> Let me experiment with this, and I'll come back with the results.
>
> Best regards, Julian
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
Ok.
On the current master checkout, run:
mvn bundle:baseline
You'll get warnings like
[WARNING] org.apache.commons.collections4.bag: Excessive version
increase; detected 4.6.1, suggested 4.6.0
because the export version needlessly changed.
Then remove the deprecated ArrayStack class (and test); run again:
[ERROR] org.apache.commons.collections4: Version increase required;
detected 4.6.1, suggested 5.0.0
(correctly)
Of course running the bundle plugin can be integrated into the normal
build process.
The *correct* (semver) export versions can be configured in the pom, or,
better in the package-info files (with the obvious advantage of the
metadata being closer to the java code).
Like that:
https://github.com/apache/jackrabbit-oak/blob/trunk/oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/sort/package-info.java
Note that the above case is a nice example; it makes the build fail as
soon as ArrayStack is removed.
Best regards, Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: Bundle versions vs API changes
Posted by Julian Reschke <re...@apache.org>.
Am 30.09.2026 um 21:05 schrieb Gary Gregory:
> Hi.
>
> Unless the plug in figures out what's what by itself on a per package
It does.
> basis, this will be unmaintanable IMO. I don't see the point of this anyway
> since we publish a JAR file, not packages.
The JAR files contains packages, no?
OSGi allows you to restrict what other components see (can use), and it
also declares which other packages (versions) it needs. That's useful
when using generic stuff like other commons components or maybe SLF4J
etc. All that goes into MANIFEST.MF.
(and yes, there likely are other approaches, but OSGi is what I know)
Let me experiment with this, and I'll come back with the results.
Best regards, Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: Bundle versions vs API changes
Posted by Gary Gregory <ga...@gmail.com>.
On Wed, Sep 30, 2026, 14:38 Julian Reschke <re...@apache.org> wrote:
>
>
> Am 30.09.2026 um 20:01 schrieb Gary Gregory:
> > On Wed, Sep 30, 2026 at 1:38 PM Julian Reschke <re...@apache.org>
> wrote:
> >>
> >> Am 30.09.2026 um 17:47 schrieb Gary Gregory:
> >>> Hi Julian,
> >>>
> >>> Commons in general follows sem ver: When the Commons Collection
> >>> version changes from 4.5.0 to 4.6.0 it means a new public and/or
> >>> protected API was added.
> >>>
> >>> Binary compatibility is paramount in Commons, so it is maintained as a
> >>> matter of fact.
> >>>
> >>> HTH,
> >>> Gary
> >>
> >> I get that; but that's per bundle, not per package, right?
> >
> > Per... Java package? What tool do you use to generate that info?
> >
> > Gary
> That's the maven bundle plugin.
>
> It will compare with the latest release, and will fail the build if the
> package version is not properly updated (and warn, when it as but
> doesn't need to).
>
> Package versions can either be specified in the pom, or in the
> package-info files.
>
> I can do some testing tomorrow (so to see what it reports for
> commons-collections).
>
Hi.
Unless the plug in figures out what's what by itself on a per package
basis, this will be unmaintanable IMO. I don't see the point of this anyway
since we publish a JAR file, not packages.
Gary
>
> (and here's what ChatGPT - like it or note :-) says:
>
> https://chatgpt.com/s/t_6abd56a054a08191ac91857fcf336b30
>
> Best regards, Julian
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
Re: Bundle versions vs API changes
Posted by Julian Reschke <re...@apache.org>.
Am 30.09.2026 um 20:01 schrieb Gary Gregory:
> On Wed, Sep 30, 2026 at 1:38 PM Julian Reschke <re...@apache.org> wrote:
>>
>> Am 30.09.2026 um 17:47 schrieb Gary Gregory:
>>> Hi Julian,
>>>
>>> Commons in general follows sem ver: When the Commons Collection
>>> version changes from 4.5.0 to 4.6.0 it means a new public and/or
>>> protected API was added.
>>>
>>> Binary compatibility is paramount in Commons, so it is maintained as a
>>> matter of fact.
>>>
>>> HTH,
>>> Gary
>>
>> I get that; but that's per bundle, not per package, right?
>
> Per... Java package? What tool do you use to generate that info?
>
> Gary
That's the maven bundle plugin.
It will compare with the latest release, and will fail the build if the
package version is not properly updated (and warn, when it as but
doesn't need to).
Package versions can either be specified in the pom, or in the
package-info files.
I can do some testing tomorrow (so to see what it reports for
commons-collections).
(and here's what ChatGPT - like it or note :-) says:
https://chatgpt.com/s/t_6abd56a054a08191ac91857fcf336b30
Best regards, Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: Bundle versions vs API changes
Posted by Gary Gregory <ga...@gmail.com>.
On Wed, Sep 30, 2026 at 1:38 PM Julian Reschke <re...@apache.org> wrote:
>
> Am 30.09.2026 um 17:47 schrieb Gary Gregory:
> > Hi Julian,
> >
> > Commons in general follows sem ver: When the Commons Collection
> > version changes from 4.5.0 to 4.6.0 it means a new public and/or
> > protected API was added.
> >
> > Binary compatibility is paramount in Commons, so it is maintained as a
> > matter of fact.
> >
> > HTH,
> > Gary
>
> I get that; but that's per bundle, not per package, right?
Per... Java package? What tool do you use to generate that info?
Gary
>
> Best regards, Julian
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: Bundle versions vs API changes
Posted by Julian Reschke <re...@apache.org>.
Am 30.09.2026 um 17:47 schrieb Gary Gregory:
> Hi Julian,
>
> Commons in general follows sem ver: When the Commons Collection
> version changes from 4.5.0 to 4.6.0 it means a new public and/or
> protected API was added.
>
> Binary compatibility is paramount in Commons, so it is maintained as a
> matter of fact.
>
> HTH,
> Gary
I get that; but that's per bundle, not per package, right?
Best regards, Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: Bundle versions vs API changes
Posted by Gary Gregory <ga...@gmail.com>.
Hi Julian,
Commons in general follows sem ver: When the Commons Collection
version changes from 4.5.0 to 4.6.0 it means a new public and/or
protected API was added.
Binary compatibility is paramount in Commons, so it is maintained as a
matter of fact.
HTH,
Gary
On Wed, Sep 30, 2026 at 11:35 AM Julian Reschke <re...@apache.org> wrote:
>
> Hi,
>
> (apologies: written with AI help)
>
> I think it would be useful for Commons Collections to use semantic
> versioning for the public packages, rather than using the bundle version
> as the package version.
>
> There are two main reasons:
>
> 1. The bundle version and package version represent different things
>
> For example, suppose we have:
>
> 4.5.0 - existing API
> 4.6.0 - with backward-compatible API additions
>
> If the exported package version is simply taken from the bundle version,
> a consumer compiled against 4.6.0 will by default require:
>
> org.apache.commons.collections4;version="[4.6,5)"
>
> That consumer then cannot run in an OSGi container that only provides
> 4.5.0 (and yes, that happened for us in Jackrabbit Oak).
>
> This is actually the correct behavior: the consumer may use API which
> was introduced in 4.6.0, so resolving it against 4.5.0 could result in
> runtime errors such as NoSuchMethodError.
>
> With semantic package versions, the package version reflects the API
> compatibility:
>
> major = breaking API change
> minor = backward-compatible API addition
> micro = backward-compatible bug fix
>
> This gives OSGi the information it needs to resolve package dependencies
> based on the API that is actually required.
>
> 2. The bundle plugin can help maintain the versions
>
> The OSGi/bundle tooling can detect API changes and suggest the
> appropriate package version changes.
>
> That means we do not have to manually determine whether a package change
> is a major, minor, or micro change in every release. The tooling can
> identify API changes and help enforce the semantic versioning contract.
>
> The important distinction is:
>
> Bundle version: Which Commons Collections release am I using?
>
> Package version: Which version of this particular API am I compatible with?
>
> Using the bundle version as the package version effectively says that
> every Commons Collections release creates a new version of every
> exported package. That makes OSGi package version ranges unnecessarily
> restrictive and mixes product/release versioning with API compatibility.
>
> Using semantic versions for the exported packages gives OSGi a more
> useful compatibility contract, while the bundle version can continue to
> identify the Commons Collections release.
>
> I can provide a (really small) PR implementing this, including the
> necessary OSGi/bundle configuration and versioning changes, if there is
> agreement that this is a direction worth pursuing.
>
> Best regards, Julian
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org