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
<alex.henev...@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.henev...@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
