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 <[email protected]> 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 > >
