Mailing-List: contact dev-help@brooklyn.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@brooklyn.apache.org
Content-Type: text/plain; charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\))
Subject: Re: Versions in Brooklyn
From: Svetoslav Neykov <svet@cloudsoft.io>
In-Reply-To: <e32b0988-652a-d023-ae1c-176a697153cc@CloudsoftCorp.com>
Date: Thu, 22 Jun 2017 12:28:25 +0300
Cc: dev@brooklyn.apache.org
Content-Transfer-Encoding: quoted-printable
Message-Id: <D617EB5F-8C13-4850-BB40-94683D945FC3@cloudsoft.io>
References: <05318db2-8e33-11ea-0272-623cdbd1dbda@cloudsoft.io>
 <2e977696-24c3-ce55-4023-775f7fd68c76@cloudsoft.io>
 <16A5C056-8070-4696-84AE-9C72BFF94224@cloudsoft.io>
 <e32b0988-652a-d023-ae1c-176a697153cc@CloudsoftCorp.com>
To: Alex Heneveld <alex.heneveld@cloudsoftcorp.com>
archived-at: Thu, 22 Jun 2017 09:28:30 -0000

Makes sense.


> On 22.06.2017 =D0=B3., at 12:27, Alex Heneveld =
<alex.heneveld@cloudsoftcorp.com> wrote:
>=20
>=20
> inline
>=20
> On 22/06/2017 10:10, Svetoslav Neykov wrote:
>> +1 to the proposal.
>>=20
>> 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?
>=20
> 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.)
>=20
> 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.)
>=20
> --a
>=20
>=20
>> Svet.
>>=20
>>=20
>>> On 20.06.2017 =D0=B3., at 14:23, Alex Heneveld =
<alex.heneveld@cloudsoftcorp.com> wrote:
>>>=20
>>>=20
>>> I've drafted the documentation for how this could be explained to =
users.  This may be easier to grok than the email:
>>>=20
>>> =
https://github.com/apache/brooklyn-docs/pull/198/files#diff-21dacc664dfe4d=
0a156d65d768a0f0e2R28
>>>=20
>>> Best
>>> Alex
>>>=20
>>>=20
>>>=20
>>> On 19/06/2017 17:39, Alex Heneveld wrote:
>>>> Hi All-
>>>>=20
>>>> 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"
>>>>=20
>>>>=20
>>>> Further to my last mail -- we have a bit of discord between various =
versioning schemes--
>>>>=20
>>>> * 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
>>>>=20
>>>> 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).
>>>>=20
>>>> (Detailed summary on SemVer and OSGi versioning is included below =
for reference.)
>>>>=20
>>>> 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.
>>>>=20
>>>> 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".
>>>>=20
>>>> 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.)
>>>>=20
>>>> Specifically I propose that Brooklyn type versions SHOULD be:
>>>>=20
>>>>    <major> ( "." <minor> ( "." <patch> ")? )? ( "-" <qualifier>) ?
>>>>    where qualifier can have letters, numbers, "-" or "_" but NOT =
additional ".".
>>>>=20
>>>> 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.
>>>>=20
>>>> Note that the above is a SHOULD.  The only strict requirement is =
the version string MUST NOT contain a ":".  (That breaks parsing.)
>>>>=20
>>>> 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"!
>>>>=20
>>>> (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.)
>>>>=20
>>>> Returning to examples:
>>>>=20
>>>> * 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.
>>>>=20
>>>> 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!).
>>>>=20
>>>> That said if there are version strings people want that aren't =
going to be well-supported with this proposal, please shout now!
>>>>=20
>>>> Best
>>>> Alex
>>>>=20
>>>>=20
>>>>=20
>>>> APPENDIX - Comparison of SemVer and OSGi
>>>>=20
>>>> GITHUB SEMVER - =
https://github.com/mojombo/semver/blob/master/semver.md
>>>>=20
>>>> *<major> "." <minor> "." <patch> ( "-" <pre_release_id> )?  ( "+" =
<build_id> )?*
>>>>=20
>>>> 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
>>>>=20
>>>>=20
>>>> OSGI VERSIONING - =
https://www.osgi.org/release-4-version-4-3-download/ - sections 1.3.2 =
and 3.2.5
>>>>=20
>>>> *<major> ( "." <minor> ( "." <micro> ( "." <qualifier> )? )? )?*
>>>>=20
>>>> The first three parts are the same as semver, except leading zeros =
are allowed.
>>>> <qualifier> consists of letters, numbers, "-", and "_".
>>>>=20
>>>>=20
>>>> SUMMARY OF DIFFERENCES
>>>>=20
>>>> (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
>>>>=20
>>>> END
>>>>=20
>=20