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