brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Heneveld <>
Subject Versions in Brooklyn
Date Mon, 19 Jun 2017 16:39:59 GMT

Hi All-

TL;DR - I am proposing that we encourage versions in Brooklyn of the 
form "1.1.0" or "1.2-qualifier" such as "1.2-SNAPSHOT", silently mapping 
when needed to OSGi as "1.1.0" or "1.2.0.qualifier" / "1.2.0.SNAPSHOT"

Further to my last mail -- we have a bit of discord between various 
versioning schemes--

* GitHub SemVer - which everyone talks lovingly about (though often not 
knowledgeably, and it's stricter than I realized!)
* OSGi versioning - a precursor to (1), in widespread use but I've never 
heard anyone say anything nice about it
* Maven - allows whatever you want but has recommendations and 
conventions most people kinda follow

They all agree on up to three numbers at the start.  It's what comes 
after that varies, usually either a "-" (semver, maven, conventions) or 
"." (osgi), followed by qualifiers.  If practice almost everyone seems 
to do "-" followed by qualifiers -- however qualifiers in practice often 
don't follow the strict constraints of semver (no leading zeroes, no 
underscores) nor some of the maven recommendations (use of build number).

(Detailed summary on SemVer and OSGi versioning is included below for 

So far, Brooklyn hasn't had an opinion and I liked it that way. However 
when registering OSGi bundles we MUST confirm with OSGi versioning 
there.  I'm pretty sure it's NOT desirable to enforce OSGi versioning on 
types, given that few people use it.  BUT we are moving to a world where 
I think we want type versions (entity versions etc) to align with bundle 
versions:  there is really no point in types having different versions 
to their defining bundle! This makes for an incompatibility between what 
people would naturally use and what we have to use within OSGi.

With examples, my assumption is that people want to use and see strings 
like "1.1-SNAPSHOT".   But under the covers the OSGi bundle needs to 
have "1.1.0.SNAPSHOT".

I propose we resolve this by recommending a version syntax which fits 
what most things people are doing and which is bi-di mappable to OSGi.  
We use this version everywhere except where a strict OSGi version is 
needed.  We WARN if we get a non-compliant version in a place which 
might be ambiguous.  And we minimise places where we need to rely on 
mapping.  (The main place a mapping is needed is if we need to create an 
OSGi version or compare with an OSGi version.)

Specifically I propose that Brooklyn type versions SHOULD be:

     <major> ( "." <minor> ( "." <patch> ")? )?   ( "-" <qualifier>)
     where qualifier can have letters, numbers, "-" or "_" but NOT 
additional ".".

We construct an OSGi version, when needed, by replacing the first "-" 
with "." and inserting 0's if needed for a missing minor/patch. So 
"1.1-SNAPSHOT" becomes "1.1.0.SNAPSHOT" when an OSGi version is needed.

Note that the above is a SHOULD.  The only strict requirement is the 
version string MUST NOT contain a ":".  (That breaks parsing.)

Where non-compliant versions are supplied, we WARN, but things work.  We 
apply simple heuristics to create a valid OSGi version -- but the 
problem is that we can no longer guarantee uniqueness ("0.0.0-a" and 
"0.0.0.a" would be conflated), and the result is possibly quite 
different to the input (eg "v1" would become "0.0.0.v1").  For this 
reason if given a non-compliant version string we WARN what the result 
is and that the resulting OSGi version could conflict with similar but 
not-identical version strings -- but things work fine unless someone is 
trying to have different bundles for "0.0.0-a" and "0.0.0.a"!

(If version is taken from MANIFEST.MF we reverse map to find the 
brooklyn type versions, by changing the ".<qualifier>" to 
"-<qualifier>"; no warning is needed here however as there is no risk of 

Returning to examples:

* If a user specifies "1.1-SNAPSHOT" that's what they will see 
everywhere except deep within OSGi where they will see "1.1.0.SNAPSHOT"
* If a user includes a MANIFEST.MF they would have to use 
"1.1.0.SNAPSHOT" syntax there; they should still use "1.1-SNAPSHOT" in 
the (or "1.1.0-SNAPSHOT" would be fine too).  If they use 
"1.1.0.SNAPSHOT" in the things will work, but they will get 
a warning, and "1.1.0-SNAPSHOT" is what will display in the UI.  If a 
different number or qualifier (eg "1.2.0-SNAPSHOT" or "1.1-beta") is 
used, it will give an ERROR because the mapping will make an 
inconsistent OSGi version.

I think the only other big options are to require OSGi everywhere (user 
unfriendly, and bad for backwards compatibility) or completely decouple 
OSGi bundle version from type versions (overly confusing). So while I'm 
reluctant to get in to the "versions should look like XXX" I think it's 
worth it to play nicely in OSGi and semver, and the above I think is the 
simplest and best way (even if the technicalities don't look so simple 
on first read!).

That said if there are version strings people want that aren't going to 
be well-supported with this proposal, please shout now!


APPENDIX - Comparison of SemVer and OSGi


*<major> "." <minor> "." <patch> ( "-" <pre_release_id> )?  ( "+"

<build_id> )?*

The first three parts are numbers.
Where <pre_release_id> and <build_id> are dot-separated tokens made up 
of letters, digits, and "-".
Key things:
* numbers and and pre_release_id tokens must not consist of numbers with 
leading zeros (e.g. "1.01" is not valid, nor is "1.0.0-01"; but 
"1.0.0+01" is)
* "-" immediately after the patch indicates pre-release and special 
precedence rules apply
* build-id metadata should be ignored when computing precedence

sections 1.3.2 and 3.2.5

*<major> ( "." <minor> ( "." <micro> ( "." <qualifier> )? )? )?*

The first three parts are the same as semver, except leading zeros are 
<qualifier> consists of letters, numbers, "-", and "_".


(1) OSGi allows abbreviating when there is no qualifier data (e.g. 
"1.1") whereas semver doesn't (has to be "1.1.0")
(2) OSGi requires a dot before the qualifier, whereas semver uses "-" or 
"+" depending on what the qualifier is meant for
(3) OSGi permits underscores but not dots; semver permits dots to 
separate non-empty tokens


  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message