You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by Alex Heneveld <al...@cloudsoftcorp.com> on 2017/06/19 16:39:59 UTC
Versions in Brooklyn
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
Re: Versions in Brooklyn
Posted by Richard Downer <ri...@apache.org>.
An awkward problem but this is a reasonable way to approach it - it would
work for all the version strings that I personally have seen "in the wild".
In the past, if I was forking somebody else's code I might call it
"1.1.0-richard.1" but under this scheme I would simply have to call it
1.1.0-richard_1 instead. So as long as we are well documented, and provide
good error messages, then I think this is a suitable proposal.
+1
On 19 June 2017 at 17:39, Alex Heneveld <al...@cloudsoftcorp.com>
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
>
>
Re: Versions in Brooklyn
Posted by Geoff Macartney <ge...@cloudsoftcorp.com>.
+1 to your proposal, having read through the examples you give I find them
pretty convincing.
On Tue, 20 Jun 2017 at 12:30 Alex Heneveld <al...@cloudsoftcorp.com>
wrote:
> ...
> > 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.
+1 similar to my previous email I don't think we should have Brooklyn's
specs
dictated by the fact that we happen to use OSGI
> 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!
+1 that sounds good to me
>
> > With examples, my assumption is that people want to use and see
> > strings like "1.1-SNAPSHOT".
I think this is right - people are more likely to think in terms of
versions using
Maven than OSGI, and if you are using Maven you probably want to regard
the version number of your pom.xml as being the _same_ by definition
as the version of the catalog.bom you are developing.
>
>
Re: Versions in Brooklyn
Posted by Alex Heneveld <al...@cloudsoftcorp.com>.
Aled-
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
replacement
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.)
Best
Alex
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
>>> <al...@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
>>>>> <al...@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
>>>>>>
>
>
Re: Versions in Brooklyn
Posted by Aled Sage <al...@cloudsoftcorp.com>.
+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 <al...@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 <al...@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
>>>>>
Re: Versions in Brooklyn
Posted by Svetoslav Neykov <sv...@cloudsoft.io>.
Makes sense.
> On 22.06.2017 г., at 12:27, Alex Heneveld <al...@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 <al...@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
>>>>
>
Re: Versions in Brooklyn
Posted by Alex Heneveld <al...@cloudsoftcorp.com>.
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 <al...@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
>>>
Re: Versions in Brooklyn
Posted by Svetoslav Neykov <sv...@cloudsoft.io>.
+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?
Svet.
> On 20.06.2017 г., at 14:23, Alex Heneveld <al...@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
>>
>
Re: Versions in Brooklyn
Posted by Alex Heneveld <al...@cloudsoftcorp.com>.
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
>