Semantic versioning of templates

Archetype Designer has recently introduced semantic versioning of templates. This is an interesting development which could be very useful, but which may require some fine tuning of the versioning rules.

For archetypes, versioning generally starts with v0.0.1-alpha, and stays that way until the first time it’s published as v1.0.0. While the choice to not use v0.0.5 or v0.3.4 can definitely be discussed, I think the use of -alpha is a good idea, to clearly differentiate development versions from production versions.

Then there are the rules about what’s considered a major, minor or patch change, to guide the version numbering. My initial thought is that the rules we use for archetypes could be used more or less directly:

  • Major changes are changes where the new version would break backward compatibility with data persisted using the previous version
  • Minor changes are semantic changes which do not break backward compatibility, for example adding new elements
  • Patch changes are changes that don’t change or add to the semantics of the template

Thoughts?

2 Likes

Hi Silje,

Yes I agree we need to pin this down quickly now. I think you are right the basically the same rules apply.

Semver is pretty dumb about .v0 artefacts, and when we did the original smver for archetypes we all agreed that pre-publication esp,. in CKM , things were so potentially unstable that trying to track major version changes was not all that helpful.

I’m starting to think that it might actually be useful to introduce ‘proper’ semver rules for prepub templates (possibly archetypes too) along the lines of, sticking with V0 but the next number represents a major version, and the last number represents a minor version.

So V0.3.2-alpha means prepublication template with prepublication major version 3 and minor version 2. When we we are doing rapid app development I can certainly see the advantage of giving the downstream consumer a much easier way of assessing the potential impact of deploying the updated template.

Of course on publication we go right back to V1.0.0

Semver allows only 3 numbers so we would have to drop path changes but I could live with that - the build ID / MD5 hash would have changed in any case.

It would be good to get an active discussion on this. Semver has been a wee bit arcane other than for those of us using CKMs but I think there will be be big benefits if applying Semver all the way through the tooling and dev process, if we can get this right, including prePub archetypes IMO, along with proper namespacing for local archetype etc.

2 Likes

Thanks Ian,

I broadly agree with your suggestion to, both for templates and archetypes, use proper semantic versioning also for -alpha, but shifting the numbers one space to the right, and dropping patch changes. Those aren’t really that important in that stage anyway?

One interesting difference with templates vs archetypes is that, if I understand it correctly, changing the name of an element is a breaking change because it changes the path? Or isn’t it?

They actually are quite helpful for templates (I think!) maybe not so much for archetypes. I spend a lot of time gradually refining templates bouncing them back and forward with other members of a team e.g form designers and it is pretty helpful for them to know that there is a breaking change before they deploy it, even in a development environment where you expect things to break but maybe not 10 minutes before you do a demo :slight_smile:

Maybe it is dumb idea but worth consideration? Can’t do any harm. Not so bothered about archetypes but I think we will see a lot more need to control archetypes, many of which may be pre-published and NPM packages/Semver is going to be important there I suspect.

1 Like

What I meant was, in the -alpha stage patch versions aren’t too important. I agree major and minor versions are important.

2 Likes

I have never heard of anything treating the 3-part version id like this, so this would be a local interpretation - I don’t think any mainstream tools would know about this.

I don’t really know what prepublication major version 3 and minor version 2 really means; to me the version is just what it says: 0.3.2. The v0 means you are not expected to follow the rules of v1+, so by definition, that means that there is no reliable interpretation of position 2 = ‘minor’ (additions allowed) or position 3 = ‘patch’ (bug fixes).

That is a breaking change in archetypes and templates (in ADL2 - just a special archetype) - because the path at which some particular element is found changes; this is like changing the ‘interface’ of any API.

Are you arguing for a 4-part version id, within v0? This isn’t supported by any spec or tool or ITS artefact (regexes etc) today…

2 Likes

I’m not thinking about changing the AT code, just the human readable name. That shouldn’t change the path in an archetype (as opposed to in a template)?

1 Like

Aha - right - that won’t matter - ideally though, the data item at the end of that path should have the same (approximate) meaning, i.e. not be something completely different.

2 Likes

For sure, any actual semantic changes will be a breaking change.

and we thought that was good enough (or insoluble) when we first looked at it but with time, I am starting to see that there is value in allowing archetype and template consumers some insight on whether a major or minor version change has been made to an unpublished asset, without having to do a detailed diff. When deciding whether to upgrade a local repo to take the latest unpublished archetype, it is really helpful to know if you are going to break something.

You are right the semver says almost nothing about how to handle unpublished numbering . I’m not advocating a 4 part number (that is not allowed). I’m suggesting that we can carry a major number in the minor ‘position’ and a minor number in the patch position. We can drop patch altogether for pre-pub archetypes. In semver we are at liberty to do what we like there (for unpublished assets). It will not be supported in mainstream tooling but then nothing will be supported since there are essentially no rules!!

With respect to name changes in templates - right now these probably do need to be regarded as potential breaking changes, since in 1.4 , node names are often used in querying paths, and to generate the web template short paths.

Like I said, this is a local interpretation, but it seems logical enough. We would need to look at where it needs to be documented in the openEHR specs.

Usually in the software world, a change in the second place of a v0 of something is treated informally as corresponding to a ‘major advance’ (e.g. update to architecture, or code rewrite), so thinking of it as a major version seems appropriate.

I’m not sure if using the terms ‘major’ and ‘minor’ however in this case would be a great idea, since it could easily confuse people when they also read that ‘major’ and ‘minor’ are 1st and 2nd place respectively in post-v0 versions of things. So perhaps v0.n+ means ‘breaking changes’ and ‘v0.n.n+’ means ‘compatible changes’. Others may have better ideas on this. As long as the explanations are clear and easy to understand, I think we’ll be fine.

1 Like

That makes sense to me. Draft archetypes and templates usually get a gazillion “patch” changes, so I’m pretty sure there’s no real use trying to track them.

One thing I’m wondering about though, is how do we signify, and do we need to signify, whether there are breaking or only non-breaking changes from v0.8.3-alpha to v1.0.0 ?

1 Like

That is a good question but just by changing from .v0 to .v1, is itself a breaking change, even if the internal structure is unchanged.

We could put all sorts of other flags in there but TBH, I’d probably hold off unless/until there is clear need.

2 Likes

I guess we could make rules that all changes should be incorporated in 0.x.y versions before publication, and that there shouldn’t be any changes between the last 0.x.y version (the release candidate?) and 1.0.0?

2 Likes

I would simplify all this. If I’m not wrong, an v0 artifact means that you can use use at your own risk and with no guarantees of quality and/or continuity. In that case, talking of major and minor changes, or breaking changes, seems unnecessary to me. I would go with just a v0.n+ incremental number, similar to the continuous release number of many software nowadays.

1 Like

Yep, the changes can be massive, especially in early drafts and for archetypes that can’t easily be aligned with existing patterns. Concept, scope, content - any or all can change as the model is tested IRL use cases. Use v0 archetypes, especially early drafts, with caution because they’ll almost certainly be significantly changed by the time it is published - that is the sure outcome of an open peer review publication process :slightly_smiling_face:

Formal governance kicks in at v1.0.0 and needs to be strict and consistent.

2 Likes