Hi Ian and Sebastian, The rule figured by Sebastian and the explanation by Ian looks very clear, thank you. But we will need to additional rule/guide to make it clear what is 'major' or 'minor', in the next step. For example, if the archetype was converted from ADL 1.4 to 1.5(or later), is this minor change or major change? ADL conversion may break compatibility for machine readability, but not change in clinical semantics. If an archetype was changed to be semantically incompatible, I think they should not be assigned for same archetype id.
regards, Shinji 2014-10-02 1:16 GMT+09:00 Ian McNicoll <ian at mcmi.co.uk>: > Hi Shinji, > > For clarity ... > > CKM 'revisions' have nothing to do with the official openEHR > major.minor.path numbers. They are an internal format to do with the local > workflows inherit in openEHR. We have discussed changing CKM 'revision' to > something else to make this clearer. > > The official major.minor.patch number proposals are intended to be neutral > to the use of CKM or any other repository tool, even the use of a simple Git > repo, and make no assumptions about how the assets are organised within that > repo e.g a git-based repo may have a quite different Trunk/branching method > and use branch names/ tags to handle internal workflow. > > The aim of the openEHR major.minor.patch scheme is to ensure that where an > archetype is used outside of a repo, in tooling or in applications, that the > consumer can be very confident about the exact provenance of the archetype > and especially its stability. > > So ignore what CKM does internally, that is not important in this context. > In the future each archetype in CKM (and we hope other controlled repos) > will also label every asset and version of the asset using major.minor.patch > -XX + build, alongside what ever local internal versioning scheme they > require. > > Ian > > On 1 October 2014 17:00, Sebastian Garde > <sebastian.garde at oceaninformatics.com> wrote: >> >> >> On 01.10.2014 17:02, Shinji KOBAYASHI wrote: >> >> Hi Ian, >> >> I would prefer https://github.com/flazz/semver/ , but not explain :) >> CKM shows archetype revision history tree, but the version is not changed. >> For example, openEHR-EHR-OBSERVATION.blood_pressure version has been >> kept 1 in these years, but it has 26 revision up. >> I think it is non-sense to change version by each revision commit, but >> meaningful change should be reflected to the version number, such as >> adding item, fixed typo, translation to other language completed. >> >> Hi Shinji, >> >> With the new revision rules a la SemVer we now have: >> >> The major version would change with an incompatible change (=the current >> v1, v2, etc identifier) >> The minor version for a compatible change which could change the meaning >> even if only slightly >> The patch version for e.g. fixing a typo in a translation. >> >> There are some grey areas, but the intention is clear I think. >> In CKM, you can do this with the new revision rules. CKM will suggest a >> new revision number based on this general idea. >> In any case you can always go higher - if you think a patch change is so >> significant because of the wording that has changed, it can also be a minor >> (or even major) version increase, i.e. instead of going from v1.0.0 to >> v1.0.1, you go to v1.1.0 >> >> To take the example of the BP archetype that you mention: >> The archetype was published in Rev 16 in 2009. >> Since then it has encountered several more changes to it like adding a >> couple of translations. >> None of these would be a breaking change to my knowledge. So, in the old >> rules it just remains v1. >> With the new revision rules, the archetype would have been published as >> v1.0.0 in 2009 and would now maybe be v1.2.4 (or whatever) - which means it >> had a number of patches and 2 minor version changes in total, none of them >> backwardly incompatible. >> >> Is this the kind of stuff you are missing? If so, this is exactly what the >> revisioning rules are there for. >> Cheers >> Sebastian >> >> >> >> Shinji >> >> 2014-10-01 23:05 GMT+09:00 Ian McNicoll <ian at mcmi.co.uk>: >> >> Hi Shinji, >> >> Github is your friend - see https://github.com/npm/node-semver >> >> but I agree, it is tricky. >> >> However it is simply not possible to manage the transition between stable >> and published archetypes safely by just using numbering alone. We need to >> very explicitly flag that unstable state so that it can be parsed safely - >> this is what the '-' gives us. We did look at all sort of numbering >> schemes >> and alternatives to Semver but eventually came back to the view that this >> is >> pretty well how it has to work. One big advantage of sticking with Semver >> is >> that we can take advantage of work like the NPM parser, apart from the >> >> The 'exclusive revision history' (if I understand you correctly) comes >> from >> the Build identifier, identified by a '+' >> >> So an unstable archetype may be >> >> v1.0.1-unstable+145567345 >> >> and after some internal authoring or reviewing goes to >> >> v1.0.1-unstable+35634512 >> >> The build identifier is not guaranteed to be sequential and there may well >> be breaking changes between the first and second iteration. >> >> From the developer perspective I can know exactly which build of the >> archetype I am using in my system, and that it is unstable. I would be >> very >> unwise to use this in any production system but may of course need it in a >> testing phase, or need to support its use within tooling. >> >> I am not wedded to -unstable , but I think you will find that if you try >> to >> work with some other number=based system, you always hit a problem ,and >> that >> some kind of pre-release signifier is required. >> >> If we agreed that openEHR would only officially support -unstable (or >> -alpha) and -rc, that would greatly simplify the parsing. >> >> Ian >> >> >> Ian >> >> >> Implementers do not have to parse what comes next >> >> On 1 October 2014 14:34, Shinji KOBAYASHI <skoba at moss.gr.jp> wrote: >> >> Hi Ian. >> >> I have read once SemVer, but it is still confusing about suffix. >> especially "alpha.11 > alpha.beta > beta.1" sequence. This needs >> tricky grammar rule to parse. >> >> Hi Sebastian, >> >> I think revision history should be exclusive, even it is unstable version. >> >> Regards, >> Shinji >> >> >> 2014-10-01 21:26 GMT+09:00 Ian McNicoll <ian at mcmi.co.uk>: >> >> Hi Shinji, >> >> Can I suggest you read the semver.org specifications? Semver is now used >> pretty widely in systems and tooling (including the nodeJS Package >> Manager >> NPM). We have taken the - suffix directly from those specifications and >> in >> other respcts we are now following semver exactly so there should be >> open >> source parsers out there that can be used. >> >> >> Semver exists because we have to treat semantic specifications >> differently >> from normal software builds. In normal software alpha, beta, pre-release >> and >> indeed the numbering chosen do not need to have any computable >> significance. >> Windows 9 is only called Windows 9 for marketing reasons ,not because it >> represents a breaking change. My recent Yosemite Beta 3-> Beta 4 update >> may >> make all sorts of breaking changes but is still a Beta and appears to be >> only a build different from the Developer Pre-release Yosemite >> candidate. >> >> When we are dealing with Semantic artefacts such as APIs or archetypes, >> the >> numbering scheme and suffixes have very specific meanings and rules, to >> do >> with backward compatibility. >> >> The -suffix is necessary to make it very clear that this is a >> pre-release >> artefact and that the normal versioning rules do not apply. What comes >> after >> the suffix does not really matter and >> >> The prime responsibility we have as archetype authors is to make sure >> that >> developers know whether they are working with a stable, published >> archetype >> which has followed the versioning rules, or an unstable archetype where >> those rules are temporarily suspended. >> >> It is impossible to do this clearly with a numbering schema alone which >> is >> why the - suffix is well-established in SemVer and the tools which use >> it. >> >> In normal circumstances unstable archetypes would never be used in >> production systems. >> >> Ian >> >> >> On 1 October 2014 13:04, Shinji KOBAYASHI <skoba at moss.gr.jp> wrote: >> >> Hi Ian, >> >> I prefer V0, because it would be easier to adopt for other developers >> who do not know openEHR well. >> For parser implementation, 1.0.0-unstable is not a good design, >> because it is not clear that which is the later release amongs, >> unstable, testing, pre-release, release-candidate, draft, etc... >> I would suggest 0.9.9 instead of 1.0.0-unstable. We can revise the >> revision 0.9.9 after it released, to 0.9.9.9. or 0.9.9.99. >> >> Shinji >> >> 2014-10-01 19:23 GMT+09:00 Ian McNicoll <ian at mcmi.co.uk>: >> >> Hi all, >> >> Apologies for cross-posting in both clinical and technical but this >> does >> neatly cross that divide. >> >> We are getting close in CKM to implementing the ADL1.5 archetype >> naming >> /versioning rules proposed at >> >> >> >> http://www.openehr.org/wiki/display/ADL/Knowledge+Artefact+Identification >> >> mostly by adding the metadata to the ADL other_details section, which >> means >> we can carry the information in ADL 1.4 archetypes without disturbing >> current systems. >> >> These latest proposals are now very much in line with the de-facto >> standard >> SemVer 2.0 see http://semver.org which allows >> >> major revision >> minor revision >> patch >> build >> >> but one of the questions which remains controversial is whether to >> support a >> major revision of V0 (as allowed in SemVer). >> >> In Semver, V0 is allowed for very immature ?first draft? semantic >> artefacts/APIs prior to initial release but SemVer allows for any >> revision >> to appended with a pre-release modifier >> >> e.g. v2.0.0-alpha or v1.0.0-unstable >> >> This is recognised as meaning that the artefact is unstable and the >> version >> numbering cannot be relied on e.g to assert backward compatibility. >> >> In that sense v0.0.0 and v1.0.0-unstable are identical in terms of >> their >> ?stability? and lack of commitment to the versioning rules. >> >> So the question for us in the openEHR world is whether tooling should >> support v0.0.0, or simply use v1.0.0-unstable >> >> V0 Advantages >> >> 1. The archetype is clearly marked as immature >> 2. Full compliance with SemVer >> 3. Supported in current test build of CKM >> >> V0 Disadvantages >> >> 1. Tooling e.g Archetype Editor (actually ADL Parser) needs to change >> to >> support V0 >> 2. Add another layer of complexity to the archetype naming/versioning >> rules >> 3. Question arises of whether / if to convert current draft V1 CKM >> archetypes to V0 with overhead of explanation to current users. >> 4. Adds complexity where V0 archetypes are being used within >> templates, >> when >> the archetype is published and needs to be updated to V1 within these >> templates. >> >> >> V1- Advantages >> >> 1. Compliant with SemVer >> 2. Does not need any changes to Archetype Editor. >> 3. Easier transition between draft and publication states when used >> within >> templates i.e does not need V0->v1 change >> >> >> V1- Disadvantages >> 1. Does not so clearly differentiate ?first draft? archetype from >> others >> >> >> Before a final decision is made, we are interested in feedback from >> the >> community on whether V0 should be implemented in CKM and other >> openEHR >> tools, although in practice V1- will do an identical job in terms of >> version >> number governance. >> >> Regards, >> >> Ian McNicoll >> Heather Leslie >> Sebastian Garde >> Thomas Beale >> >> >> >> _______________________________________________ >> openEHR-technical mailing list >> openEHR-technical at lists.openehr.org >> >> >> >> http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org >> >> _______________________________________________ >> openEHR-technical mailing list >> openEHR-technical at lists.openehr.org >> >> >> >> http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org >> >> >> -- >> Dr Ian McNicoll >> office / fax +44(0)141 560 4657 >> mobile +44 (0)775 209 7859 >> skype ianmcnicoll >> ian at freshehr.com >> >> Clinical modelling consultant freshEHR >> Director openEHR Foundation >> Honorary Senior Research Associate, CHIME, UCL >> BCS Primary Health Care www.phcsg.org >> >> _______________________________________________ >> openEHR-clinical mailing list >> openEHR-clinical at lists.openehr.org >> >> >> http://lists.openehr.org/mailman/listinfo/openehr-clinical_lists.openehr.org >> >> _______________________________________________ >> openEHR-clinical mailing list >> openEHR-clinical at lists.openehr.org >> >> >> http://lists.openehr.org/mailman/listinfo/openehr-clinical_lists.openehr.org >> >> >> -- >> Dr Ian McNicoll >> office / fax +44(0)141 560 4657 >> mobile +44 (0)775 209 7859 >> skype ianmcnicoll >> ian at freshehr.com >> >> Clinical modelling consultant freshEHR >> Director openEHR Foundation >> Honorary Senior Research Associate, CHIME, UCL >> BCS Primary Health Care www.phcsg.org >> >> _______________________________________________ >> openEHR-technical mailing list >> openEHR-technical at lists.openehr.org >> >> http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org >> >> _______________________________________________ >> openEHR-technical mailing list >> openEHR-technical at lists.openehr.org >> >> http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org >> >> >> -- >> >> Dr. Sebastian Garde >> Dr. sc. hum., Dipl.-Inform. Med, FACHI >> Ocean Informatics >> >> Skype: gardeseb >> >> _______________________________________________ >> openEHR-technical mailing list >> openEHR-technical at lists.openehr.org >> >> http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org > > > > > -- > Dr Ian McNicoll > office / fax +44(0)141 560 4657 > mobile +44 (0)775 209 7859 > skype ianmcnicoll > ian at freshehr.com > > Clinical modelling consultant freshEHR > Director openEHR Foundation > Honorary Senior Research Associate, CHIME, UCL > BCS Primary Health Care www.phcsg.org > > _______________________________________________ > openEHR-clinical mailing list > openEHR-clinical at lists.openehr.org > http://lists.openehr.org/mailman/listinfo/openehr-clinical_lists.openehr.org
