brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Svetoslav Neykov <s...@cloudsoft.io>
Subject Re: Versions in Brooklyn
Date Thu, 22 Jun 2017 09:28:25 GMT
Makes sense.


> On 22.06.2017 г., at 12:27, Alex Heneveld <alex.heneveld@cloudsoftcorp.com> 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 <alex.heneveld@cloudsoftcorp.com>
wrote:
>>> 
>>> 
>>> I've drafted the documentation for how this could be explained to users.  This
may be easier to grok than the email:
>>> 
>>> https://github.com/apache/brooklyn-docs/pull/198/files#diff-21dacc664dfe4d0a156d65d768a0f0e2R28
>>> 
>>> 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 catalog.bom (or "1.1.0-SNAPSHOT"
would be fine too).  If they use "1.1.0.SNAPSHOT" in the catalog.bom 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
>>>> 
>>>> GITHUB SEMVER - https://github.com/mojombo/semver/blob/master/semver.md
>>>> 
>>>> *<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
>>>> 
>>>> 
>>>> OSGI VERSIONING - https://www.osgi.org/release-4-version-4-3-download/ -
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 "_".
>>>> 
>>>> 
>>>> SUMMARY OF DIFFERENCES
>>>> 
>>>> (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
>>>> 
> 


Mime
View raw message