This page is for discussing schemes of versioning ITS artefacts.
Firstly, 'ITS' (Implementation Technology Specification, a term we re-used from HL7) indicates derivative (but generally hand-built) artefacts based on 'upstream' specifications or 'pure models'. We might reasonably say that UML or BMM are pure, lossless expressions of the specs. ITS artefacts are usually somewhat (or even very) lossy w.r.t. the upstream models/specs, e.g. they may only carry the data view.
Practically speaking, ITS artefacts are the concrete means of using or implementing openEHR in some particular kind of component. Someone who wants to build components using openEHR XML will need canonical XSDs, Schematron or some other kind of XML schemas. Someone who wants to do FHIR-ish kinds of things might want openEHR-flavoured FHIR resources.
The number of ITS artefacts (taking a set of linked files as a single artefact) is roughly No. Specification Components x No. extant releases x No. downstream technologies. Here,
When it comes to APIs, my original conception of any API such as REST, SOAP, or a native language API (i.e. Java, C#, ...) should also be seen as an ITS, based on a properly specified and abstractly (but formally) modelled API, expressed in say UML and/or IDL (or Ecore-ish form would also do). In other words, if we build a 'COMPOSITION' REST API with the logical function 'get composition by version' we imply that there is an underlying native service containing a function like get_composition_by_id (version: VERSION): COMPOSITION. In this approach, a SOAP, REST, Java, ... etc APIs should all do the same thing, just in their idiom.
Others here may see each kind of API as a primary artefact, that is fully self-defining semantically, and in some sense this is true right now, since we are building the REST APIs before having abstract APIs specified. I believe that the right approach would be to reverse engineer abstract APIs from concrete APIs, for various reasons - mainly, providing a gold standard of transactional semantics that need to be respected by all kinds of concrete APIs.
If you agree with this, then although we don't have an upstream API spec today, we should consider that REST APIs are still an ITS kind of artefact, and that we will build those abstract definitions later. If you don't agree, then you may argue that the REST APIs are not ITS artefacts at all.
Organise the ITS repo(s) in such a way that :
We had various conversations in the past about this, and the various proposals, in brief are:
This is one approach we discussed at last year's SEC meeting (wiki notes here), where each component (RM etc) has its own ITS repo, and successive releases (1.0.0, 1.0.1, 1.0.2, 1.0.3 etc) are on a single line of development and essentially replace each other.
pros:
cons:
This is the usual approach applied to primary artefacts, particularly software, that are continually maintained in multiple extant versions. Concretely here it would involve a repo per upstream component (RM, AM, SM, etc) and the use of formal branches inside each repo. Pablo also provided a diag here.
Repos:
pros:
cons:
The is the approach some of us I believe arrived at in later conversations last year. It is a pragmatic approach, and results in a repo that uses a directory structure based on upstream release ids as the structure. One such structure is:
Other structures are possible, e.g. factored by ITS technology rather than upstream component:
Sebastian's preferred structure (9 July 2018):
Sebastian Iancu: one thing we discussed about was that actually each technology (XSD, etc) will have to be released/implemented for each release of the underlying artefact (RM/SM/etc), and all have to be maintained in parallel for a while (so XSD 1.0.2, 1.0.3, 1.0.4 should be maintained for a while). Besides that, we might have typos or implementation specific issues that we might want to correct - these are not RM/SM/etc related. My Impression is that overall we'll be better with one single big repo (and is still manageable) - but if I'm somehow wrong, I think we can always split it later in several small ones.
To avoid confusions, we could release the upnext as the v2.0.0 of ITS, since the whole structure is going to be changed. Or even more, we can name it 2018.8 (so yyyy.m) to be sure nobody will confuse it.
The particular structure probably doesn't matter that much, since either way, it's an everything-at-once approach.
pros:
cons:
Separate repos for
If we think that these technology expressions are relatively independent of each other, it could make sense. Also, then REST Release-1.0.0 is the release of the whole repo, and we don't get the confusion of ITS 1.1.0 = REST APIs 1.0.0.
pros:
Sebastian Iancu:
I generally agree with principle 1repo=1tech, it will indeed make life easier to maintain it, to own it.
But I'm still not sure if it is the best answer here. We should not forget that history/releasing 1tech is not always equal (in sync) with RM release. As an exercise, lets look to the current state:
My point is that any new release in RM / AQL / AOM / etc, might require a new release on REST, but we might need to have also new releases that are not "triggered" by RM / AQL / AOM. And we might need maintain these releases as (parallel) branches, as not all implementations is using latest RM / AQL / AOM / etc.
Another point is that REST requires data models to be described by a schema (JSONSchema or XSD) - so yes they are different techs (in two or more different repos) but sometimes they might need to be released together.
How are we going to manage all these? We can have a big giant repo where we have to structure things in a smart way or ...if we go for different repos, don't we need then something like a dependency map? (something like the npm / composer *.json file)