Versioning for models

[jeromesimeon]

Models should be versioned so changes do not break existing templates. This may be particularly sensitive since we refer/access them using URI.

[mttrbrts]

Problem

Changes to models should be managed so that dependent projects can reliably incorporate backwards compatible changes and block breaking changes.

Today, once a model is published it can not be easily modified, in case it should break a dependent system. For example, renaming an attribute in a concept or adding a new non-optional attribute will cause validation failures for systems that are unaware of breaking changes.

New model versions can be released, but require unique URI / filenames to distinguish them from older versions. There is currently no standard convention for making name changes. See https://models.accordproject.org/time.html, https://models.accordproject.org/v2.0/time.html

This restriction makes contributors hesitant to make changes to models in case they break dependent systems.

Proposal

Versioning for models should be based on a semantic version in the filename. Models should not be packaged into archives (as templates are).

Syntax in this proposal is indicative only.

For example:

model@0.1.0.cto
model@1.2.3-alpha.cto

model-0.1.0.cto
model-1.2.3-alpha.cto

This will allow the current mechanism for importing models by name in Concerto and Ergo to continue to work unchanged. e.g.

import org.accordproject.cicero.runtime.* from https://models.accordproject.org/cicero/runtime@0.1.0.cto

Future enhancement

To allow model references based on semantic version expressions, e.g. ^0.1, > 2.1 | <= 3.4, we could make the following changes.

1. Modify the import syntax to include a semantic version expressions, for example:

   import org.accordproject.cicero.runtime.* from https://models.accordproject.org/cicero/runtime.cto@~0.1

   The absence of an expression would default to the existing behaviour.

2. Repositories that host models should include an index.json in each directory that lists the available models.

3. When downloading a model, the resolver should first download the index file and find the most recent model instance that satisfies the expression. This can be determined by sorting according to the usual semver precedence rules, and selecting the first version that satisfies the expression.

4. The page generation code in this repository could collapse models with the same base name into the same page, to avoid bloating pages with many versions of models. Perhaps similarly to the dropdown for versions at templates.accordproject.org.

5. [Optional extension] It is feasible that tooling could be developed to recommend a version change based on a model change. For example, a diff between models should be able to reveal the nature of the change and bump the version accordingly. @jeromesimeon?

[mttrbrts]

@jeromesimeon @dselman Do you have any preference on the filename structure?

For example:

model@0.1.0.cto
model@1.2.3-alpha.cto

model-0.1.0.cto
model-1.2.3-alpha.cto

The second option follows the pattern used by other web-resources, e.g. https://code.jquery.com/jquery-3.4.1.min.js, however, using the dash as a delimeter makes it more difficult to parse the semver string because - is a valid character to denote a prerelease.

[dselman]

No strong preference. Note that we also use the @ prefix to denote models downloaded from external URLs in templates.

[jeromesimeon]

We've been using @mttrbrts 's versioning strategy for a while now. Closing this issue.