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 <[email protected]> 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: [email protected] > For additional commands, e-mail: [email protected] > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
