+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 <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 >> >
