I just posted this at [SPECAM-72] Consider improving 'version tracking' for unpublished archetypes - openEHR JIRA
When we developed the current archetype versioning rules, based on Semver, the rules around unpublished artefact version tracking in Semver was (and still remains) pretty loose.
We decided to live with that in the context of CKM as it uses MD5 hashing to ensure proper ‘hook-up’ of versions e.g archetypes in templates, and from the perspective of CKM editors/reviewers, strict version tracking is not that useful.
However, at application dev level, where we are often doing things pretty fast, it is becoming increasingly important to identify breaking changes , or potential breaking changes both to modellers and downstream artefacts.
We probably do not want to break the .v0 commitment - to make it very clear that this is a draft artefact but need to shoehorn the major.minor identifiers in there in a consistent way that can be applied cross-tooling.
One option is to shift-right the major.minor numbers
so V0.major.minor
V0.major.minor.patch breaks semver rules but I could probably live without carrying patch (only really matters if translations are added).
when published we would always jump to V1.1.0, regardless of where we got to in the V0 cycle.
Fabio is busy implementing semver in Archetype Designer so early consideration would be helpful.
Right shift - interesting idea, I had never heard of that, but it’s got an attraction.
Please not 4 fields though, because everyone’s software is full of regex and other recognisers for 3-part not 4-part version ids (potentially with ‘-rc’ and such things on the end).
That v1.1.0 doesn’t sound right though - the first controlled release should be v1.0.0, surely? v1.1.0 will make people think there have been at least one minor version update, when there hasn’t…
You are correct - it is 1.0.0 … Sebastian picked that up and commented on JIra.
1.0.0 for published 0.1.0 for unpublished.
@borut.fabjan was equally opposed to the 4 fields - and I’m ok with that ‘patch tracking’ is really not important. The only significant patch changes are translations
Let’s keep it to syntactically valid sem ver.
If you want patch as an explicit field, I think 0.1.1+1 would be valid syntactically (where the final +1 indicates a build), but not sure I would go there. Combining minor and patch seems fine to me. And you always have the choice to bump up the second digit, even if it is not technically a major version/ incompatible change.
I don’t have a real preference for 0.1.0 or 0.0.1 as initial number. I don’t mind 0.0.5 and find it useful as Thomas, also it would be a change in the [openEHR identification] spec. The way I read the Sem Ver spec, starting with 0.1.0 is just the “simplest” way. This “simplest” way (see:
Semantic Versioning 2.0.0 | Semantic Versioning ) by the way also recommends to just increment the second digit with each release (0.1.0 → 0.2.0 → 0.3.0 no matter what).
It is just that: the simplest, but not the only possible way manage pre-publication version numbers.
Agree re patch. If we find we really need it, there are options outwith the three fields but marginal value right now.
And that was roughly speaking where we settled last time around but I now think there is considerable value in tracking things ‘properly’.
What is the current idea of ‘properly’ - just the 0.major.minor thing, or starting point = 0.1.0 as well? My own preference would be the former, but not the latter. How about we document that the ‘default starting version is 0.1.0 unless there is a specific intention to signal some other maturity’, or similar?
Sorry confused things. I think the 0.1.0 is a no-brainer as the ‘initial’ version. In line with current semver spec. I don’t think anything at all will break right now and it was always only advisory/
By ‘properly’ I meant v0.major.minor (or an alternative) that lets us differentiate unpublished major from minor revisions.
AD now has some nice diffing capacity and hints of change impact, similar to CKM.
So the idea is that with the rightshift trick, the diffing tools will work properly between 0.x versions of something? Seems like a good idea…
I don’t see a need for changing the (minimal) initial version from the currently specified 0.0.1.
SemVer does not say you must start with 0.1.0 - you just can if you like and it makes sense especially if you only increment the minor version anyway. But 0.0.1 is just as valid.
2 Likes
