Archetype Naming proposals - do we need V0?

Clinical (archive)
1

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

2

Hi Ian,
Personally I think V0 has significant costs in exchange for not so significant benefits. Semver compatibility would be nice, but nice is not worth the implementation cost for parser etc here. I don’t know if V0 support would break things deep down in actual openEHR implementations but even that may be a possibility if there is a reg-ex sitting in some code that expects v1 as the starting point.
The features in adl 1.5 would probably help provide a workaround to express the semantics that would otherwise be expressed with V0

Best regards
Seref

3

Thanks Seref,

That is my feeling exactly. In practical terms, in an openEHR context, .V0 and .v1-unstable are identical. We do know that V0 breaks the old AE Eiffel parser. This is probably easily fixable but is an example of work that would need to be done.

We are replicating the ADL 1.5 features as you suggest but in a way that does not change core archetype identification in ADL1.4, other than .V0.

Perhaps the compromise is to defer the decision until tooling and systems are ready to use ADL1.5, by which time we will have experience with V1-unstable and have a better understanding of whether V0 is really necessary.

Ian

4

I tested v0 with LinkEHR editor and works just fine.
I think that 'v1.0.0-unstable' has additional problems, such as
deciding which words are allowed (e.g 'unstable', 'firstdraft',
'alpha', etc.), which means that tools have to be modified anyway.
Arguably, is better to widen a range than to parse specific strings
which end changing in the end.

Also, adding this breaks all current v1 slots (related to my last
question to the list)

v0 is also fully compliant with SemVer, which means that in theory
archetype identifiers won't need to be changed when we move to ADL1.5
(going with v1-unestable will need another change in the future)

5

Hi Diego,

Just to be clear, under ADL1.4 the -unstable suffix (and other naming metadata) will not be added to the archetypeID but will be carried in the other_details metadata, so it does not disrupt current tooling. It is up to developers to decide how much of that metadata to make use of for now. When we move to ADL1.5 these new ‘other_details’ metadata items will become formal AOM and RM attributes but I think Thomas plans to keep the core archetype_id identical, again to minimise disruption.

The only exception in ADL 1.4 is that V0 (if adopted) will potentially break some tooling or back-end systems. None of the other changes should cause things to break as long as other_details is supported correctly. Glad to hear LinkEhr is behaving correctly. We have made some changes to Archetype Editor, which will be released shortly, to ensure that other_details behaves equally well!!

So until ADL1.5 comes along -unstable will not break anything. Semver does not actually specify which ‘pre-release’ labels are allowable.

After a lot of discussion we decided that there were really only 2 pre-release states that have semantic significance in openEHR (and probably other archetypes)

unstable => This archetype is in development or re-development and the formal Major/Minor/Patch identifiers cannot be relied upon as an indicator of whether the archetype is backwardly compatible i.e once the archetype enters an unstable state, the formal version numbering will remain unchanged, even though the archetype itself is not backwardly compatible. The major/minor/patch numbers will only be adjusted at time of publication or re-publication or when it goes into pre-release state - se next

pre-release=> This archetype is still in development but the authors are confident that any future changes that are made will be trivial, and as such are prepared to adhere to the formal version numbering rules, just as if the archetype was fully published.

CKM will not allow ‘pre-release’ to be set (for now).

We can discuss allowing alpha, beta etc but really all that developers need to know is that once the -unstable flag is set, they need to be aware that this archetype is really not fit to be used operationally and is ‘at your own risk’. The additional Build number identifies the archetype instance very specifically.

Ian

6

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

7

Hi Ian, I don’t think this is true. Firstly, the standard first possible version is v0.0.1 in any versioning environment I know of; secondly, the rules that I thought we were adopting have the following implications: I may still be missing something here, so this analysis is what seems sensible to me based on what I know today. - thomas

8

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

9

Hi Thomas and all,
The point when it becomes v1.0.0 is when the archetype is first published - i.e. the first published version will always be 1.0.0 and not v1.2.0 If the transition to v1.0.0 comes from v0.0.1[-unstable] or v1.0.0-unstable doesn’t really matter - purely technically speaking the terms of stability and lack of commitment are the same for both 0.0.1[-unstable] and v1.0.0-unstable Supporting it as part of the specs for uncontrolled/chaotic development is one thing and I agree. But what we are looking at here is that all CKM archetypes would have a v0 extension until they are first published (as v.1.0.0). Existing pre-publication CKM archetypes would be converted to have a v0 extension (either as a batch or one-by-one when each one is updated the next time) That’s not really an option unless you want to make this migration even more difficult. What you are suggesting requires two different sets of rules and someone needing to deciding which stays at v1 and which is converted to v0. I don’t think it makes sense - either we use v0 to indicate pre-publication archetypes or we don’t. Sure, looking forward to tooling support on it, but realistically at the moment it is a pain that is not needed for the first publication if you go with v1 as a the initial major version. Sebastian

10

Hi Thomas,

I agree with all you haver said but would stick to my original assertion that for *practical’ and computable purposes, in terms of fitness to be used in an operational system and adherance to the version number rules, v0.0.1 and v1.0.1-unstable are identical.

Both, when published will end up as V1.0.0, both are unstable.

I can see the human argument for differentiating a truly feral archetype from one in a controlled repository but am not convinced that this outweighs the hassle of supporting V0 in ADL1.4.

When we move to ADL1.5 tooling and downstream systems will need to be changed in any case, so perhaps that is the point to formally introduce V0?

Agree with your other points and examples.

Ian

11

Actually, this is clearly defined by SemVer, see rule 11: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0. But I don’t think we would usually want to do this at all for unstable archetypes. They are just unstable, no guarantee whatsoever. If you want to have a specific one, you can always use the unique build id for that. Sebastian

12

Hi Diego,
That’s great, although in this case I think you are actually being too lenient if you strickly stick to the current spec which defines a V_IDENTIFIER as [a-zA-Z][a-zA-Z0-9_]+(-[a-zA-Z][a-zA-Z0-9_]+){2}.[a-zA-Z][a-zA-Z0-9_]+(-[a- zA-Z][a-zA-Z0-9_]+).v[0-9] v1.0.0-unstable is also fully compliant with SemVer - I don’t understand why this would require more changes in the future that v0 doesn’t need? Sebastian

13

Thanks Sebastian,

You are correct, of course, there is a rule about this, but is just about lexical matching e.g. -a is allowable and -a < -alpha. The labels themselves have no meaning.

On that basis, perhaps -unstable should be renamed to something earlier in the alphabet to fit with the matching rule i.e so that it comes before -rc? On the other hand we do have a very specific meaning for rc, which is that although this is still an archetype in development, it will obey the versioning rules if it has to change.

Ian

14

that sounds right to me - is it a problem? I would have thought that individual archetypes can have their version modified? I don’t think the world minds if there is a period of a few months during the industry sprint when the rules are technical being broken. Once it’s done, there will be 70+ archetypes with v1.x, and the rest with v0.x, and that will correctly represent the situation of the archetypes in CKM. Then for every mirroring, copy, and reuse of what’s in openEHR.org CKM, there is no need to educate anyone on anything - it’s obvious what the situation is. So we are only talking about a limited period of time where the rules are being broken (as they are right now in fact :wink: well I think its a bigger danger, given the level of reuse of CKM archetypes, that the version ids wouldn’t correct reflect the state of the archetypes. We could in theory revert everything that is not published to v0 right now, and i guess that is breaking the rules for less time. But there are still some dozens of fully reviewed and published archetypes that have to retain their v1.x version anyway. So I think the only question is to do with the industry sprint archetypes. How about doing this: If I receive a copy of archetypes marked like that in say the GitHub mirror, or through a different CKM, I don’t need any further education, it’s obvious what’s going on. - thomas

15

Yes, not really that nice, is it - it just works coincidentally. That’s one reason I said I wouldn’t want to use more than one. Good point. Still if we use -unstable and -rc, we cannot claim to fully embrace the SemVer rules for precendence. Sebastian

16

How about

-ardvaark or

-awfullybadideatousethis

I would be happy with -alpha.

I know it is a technical term but it would not normally be visible to a clinical audience, who are going to see ‘real’ publication process states like draft, team review etc.

-alpha sends the correct message to developers that this thing is risky!

Ian

17

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

18

Dear all,

I'm surprise to see such a low analysis of the impact of changing v1 to v0 of the existing CKM archetypes.
Even though they are not 'published', or are in logical 'draft' mode, they were conformant to openEHR standards for at least past 5 years or so. Some of them are used already in production environments for more than 2-3 years (at least in our case).
Changing them now on CKM will break logical binding with already existing production data. This cost has to be eventually supported by industry implementers, and I can assure you this is not trivial, and it is giving the impression that openEHR standard is not reliable/stable enough.

Basically the proposal is to rename existing CKM archetypes (published or not) in contradiction with what the current openEHR specifications is stating right now, which is not right.

Other than this, I personally think that is nice to have v0 for 'drafts', and v1 for stable-published; it might be a better indication about a state of an archetype.
So my suggestion is to keep existing CKM archetypes the way they are and only apply the new 'rule' for archetypes created from now one. Published archetypes from the sprint can become v2 (or 3, 4 etc) depends on the need (see specifications).

Sebastian
Code24

19

This is what works in a CKM test version, so no it is no problem (but is certainly more complex than it may sound) You are trying to eat your cake and have it. For semantic versioning to be implemented in CKM, the version numbers need to be under CKM control. And then for your revisioning to work, CKM needs to know which archetypes should be converted and which ones shouldn’t and then apply different versioning rules to them. I see no reason to add to the complexity like this. I don’t care when it is done. It can either be as a batch or each time you change an archetype next. But when you change it next, CKM then needs to apply the correct revisioning rules to it or it will just be an endless migration mess. I don’t see your problem. Naturally, published archetypes would not change their .v1 version to .v0. As above, then you are applying two different set of rules for migration, depending on whether the archetype is in the industry sprint or not. Apart from the additional complexity I tried to explain, what is the point? The only point I can see is that you want to identify industry sprint archetypes: I think they are all part of one project now and you can easily get them from there. Well, I for one, would not understand without your explanation that the difference between 0.5.0 and 1.0.0-unstable is that the one is in industry sprint and the other isn’t. There are more logical ways to me to find this out (just look at the CKM project). Sebastian

20

Hi Diego,

I tested v0 with LinkEHR editor and works just fine.

That’s great, although in this case I think you are actually being too lenient if you strickly stick to the current spec which defines a V_IDENTIFIER as
[a-zA-Z][a-zA-Z0-9_]+(-[a-zA-Z][a-zA-Z0-9_]+){2}.[a-zA-Z][a-zA-Z0-9_]+(-[a-
zA-Z][a-zA-Z0-9_]+).v[1-9][0-9]

We changed this 6 or 7 years ago when we removed the “v1draft” kind of identifiers that were a thing back then. We also allow the definition of single letter entities, that this regex does not allow but specifications did allow at least back then (not sure if still do). As somebody said “Be conservative in what you do, be liberal in what you accept from others” :wink:

v0 is also fully compliant with SemVer, which means that in theory
archetype identifiers won’t need to be changed when we move to ADL1.5
(going with v1-unestable will need another change in the future)

v1.0.0-unstable is also fully compliant with SemVer - I don’t understand why this would require more changes in the future that v0 doesn’t need?
Sebastian

I said that because we have to agree to a valid list of words we support for versions, and this kind of decisions are not easily taken (take for example the possible lifecycle status of an archetype).

If we also override the lexic order then we must change it to fully agree with semver