brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Heneveld <>
Subject Re: Versions in Brooklyn
Date Tue, 20 Jun 2017 11:23:53 GMT

I've drafted the documentation for how this could be explained to 
users.  This may be easier to grok than the email:


On 19/06/2017 17:39, Alex Heneveld wrote:
> 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 
> reference.)
> 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 non-uniqueness.)
> 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!
> Best
> Alex
> 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 
> allowed.
> <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