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 Fri, 23 Jun 2017 08:00:24 GMT


Well spotted.  I only realised when implementing that the bi-di didn't 
quite hold where minor/patch versions were omitted because OSGi infers 
these as 0 (this seems to be true whether or not there is a qualifier).  
So 1.0 and 1.0.0 in OSGi are the same.  This means we have two options:

(a) Brooklyn recommended syntax always takes 3 numbers, e.g. "4.6" is 
not allowed, it has to be "4.6.0"

(b) Treat missing minor/patch as equivalent to 0 for bundles, causing 

I favour (b) (which is what PR #743 does), with an extra sentence in the 
docs explaining this.

After implementing the other observation is that replacement (when 
versions collide) is minor, so I don't think it matters too much. 
Especially when types in a bundle have the same version as the bundle, 
we wouldn't normally ever get two types whose OSGi versions are 
identical.  Specifically:

(1) for non-snapshots, you can't replace if the definition is different, 
so installing a "1.0" then trying to install a different item as "1.0.0" 
will fail fast
(2) for snapshots, installing a bundle at "1.0-SNAPSHOT" then a 
different one at "1.0.0-SNAPSHOT" will result in removal of items coming 
from the first bundle
(3) the only way to get a "foo:1.0" and different "foo:1.0.0" is if one 
of those items comes from a bundle whose version is different to the 
type, and I think we want to WARN in this case (and eventually disallow 
as there's no compelling use case?)

The main surprising thing apart from the above I think is:

(3) type references have to use the exact version as specified; so if 
you install "foo:1.0" you have to reference it as "foo:1.0"; references 
to "foo:1.0.0" will fail

All of which I think is fine but if anyone is concerned say now. (We 
could change (3) but I don't see it as important.)


On 22/06/2017 18:15, Aled Sage wrote:
> +1; sounds sensible.
> You said /"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"/.
> To clarify, I think you're saying we recommend a version syntax like 
> of 1.0.0-SNAPSHOT (and discourage 1.0-SNAPSHOT), so that it is a 
> bi-directional mapping. Is that right (but examples in the docs link 
> include `1.10-rc3-20170619`)?
> Would we let users use (non bi-di mappable) 1.0-SNAPSHOT without any 
> warnings or deprecation?
> Aled
> On 22/06/2017 10:28, Svetoslav Neykov wrote:
>> Makes sense.
>>> On 22.06.2017 г., at 12:27, Alex Heneveld 
>>> <> wrote:
>>> inline
>>> On 22/06/2017 10:10, Svetoslav Neykov wrote:
>>>> +1 to the proposal.
>>>> One thing I have reservations about is having a recommended version 
>>>> syntax with other formats still supported but deprecated.
>>>> As far as I understand the recommended syntax is there so we can 
>>>> guarantee a uniqueness of the OSGi versions (when the source 
>>>> version is unique). Instead of having a recommended syntax can we 
>>>> document what we consider a unique version and let the user decide 
>>>> what format to follow?
>>> yes, we could.  but i think it's nicer in a community setting where 
>>> blueprints are being shared if versions follow the same format.  (we 
>>> could enforce the recommended syntax in the community catalog.)
>>> also i tend to think it's easier for users if we recommend a syntax 
>>> rather than have to explain about uniqueness of osgi bundles. 
>>> (currently that explanation is buried in an advanced section which 
>>> can safely be ignored.)
>>> --a
>>>> Svet.
>>>>> On 20.06.2017 г., at 14:23, Alex Heneveld 
>>>>> <> wrote:
>>>>> I've drafted the documentation for how this could be explained to 
>>>>> users.  This may be easier to grok than the email:

>>>>> Best
>>>>> Alex
>>>>> 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
>>>>>> 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
>>>>>> END

View raw message