Proposal: Versioning Strategy (Git + JSON Schema)

[vdice]

In this repository, we've yet to fully settle on a given versioning strategy for the JSON Schema files created here. Perhaps the main source of friction/disconnect is aligning a Git versioning strategy with a proper JSON Schema versioning strategy.

So far, we've tried a tag for the first official release: cnab-core-1.0

For the next CNAB Core release, we used a branching model: cnab-core-1.0.1. The intention here was to support the approved CNAB Governance mechanism for amending typographical errata without necessarily cutting a new patch release.

However, whilst exploring options for producing artifacts from this repository at pinned commits (tags or branches, etc.) in https://github.com/cnabio/cnab-spec/issues/346 and its current implementation PR (https://github.com/cnabio/cnab-spec/pull/350), it became clearer that Git tags may be the more convenient method for pinning spec/schema versions (and enabling CI to publish assets from these commits).

I may be missing some other pertinent points and may not be relaying all related issues, but I'm inclined to propose the following:

1. On each agreed spec version increment, we cut a Git tag, e.g. cnab-core-1.1.0, cnab-claim-1.0.0 and even draft versions at certain commits, such as cnab-claim-1.0.0-DRAFT+abc1234, where abc1234 represents the short Git SHA associated with the tagged commit.

   • On these events, CI will publish all schema files located in the schema sub-directory according to the tag, accessible via e.g. https://cnab.io/schema/cnab-core-1.1.0/bundle.schema.json
   • Implementing tools would then set the schema version on their corresponding implementations based on these tags. For example, a tool implementing a bundle at tag cnab-core-1.1.0 would set "schemaVersion":"1.1.0" for the produced bundle.json file. Or, a tool implementing a (working draft) claim at tag cnab-claim-1.0.0-DRAFT+abc1234 would set "schemaVersion":"1.0.0-DRAFT+abc1234" for the produced claim.json file.

2. For errata, wherein previously we may have added commits to a 'static' version branch (as in the cnab-core-1.0.1 example above), I propose we cut a new tag reflecting a patch increment. So, in this case, cnab-core-1.0.2 might consist of cnab-core-1.0.1 plus commit(s) involving errata fixes and perhaps further patch fixes.

Thoughts/ideas?

[technosophos]

Here's the wording on errata from the CNAB Foundation governance doc:

Documents that have reached AD are considered complete. Errata may be captured in a separate section of the document, but the document itself is not changed except to correct typographical and formatting errors where necessary.

So there are three sorts of changes that are allowed without instigating a new iteration of the development process:

• Errata (Clarifications and corrections of meaning)
• Typographical errors
• Formatting errors

My reading of the above is that we could release a new version of the spec for each of those, but don't need to. Is that a process burden that we are okay taking on?

/cc @chris-crone

[chris-crone]

@vdice Thanks for the proposal, I think it makes sense.

My reading of the above is that we could release a new version of the spec for each of those, but don't need to.

This is my reading too. I share @technosophos's fear that we might be creating a burden on ourselves if we put in place too much process for errata. It might make sense to handle errata ad-hoc instead of having a formal process.

For the JSON schemas, errata/typos/formatting MUST NOT change the functional aspects of the schema (i.e.: anything other than description fields). We infer this for the bundle.json but maybe should make explicit that all schemas follow semantic versioning.

[vdice]

It might make sense to handle errata ad-hoc instead of having a formal process.

I think I'd still like to establish a protocol for these cases, even if the solution isn't from the proposal above. Case-in-point, a recent PR: https://github.com/cnabio/cnab-spec/pull/353

I had another idea for a solution from that PR: Regardless if the errata-amended version is captured in Git history as a branch or a tag (though, I'm hoping we settle on tags, for reasoning stated above), it would be good to know whether the errata PR should be from the branch/tag and then cherry-picked into master or the reverse... or perhaps something different still.

I'd be fine with not enforcing that we cut a new (patch release) tag for errata-only amendments. As we've mentioned here (and the versioning doc illustrates), such amendments must not have any effect on JSON Schema validation, so I don't see a need to publish new artifacts.

[technosophos]

I've been thinking about this for the CNAB-Core-1.1.0 and CNAB-Claims-1.0.0 releases. I am thinking that maybe what makes sense is for us to create a branch for a major or minor release, and do this when we hit the GA (group approval) phase. So the branch would be cnab-claims-1.0.0-ga. This would signal that the working group has approved, and then the tag (cnab-claims-1.0.0) would be the tag for approval by the executive directors.

Then for branching strategies, we could follow what Helm does: Commits all go on Master, but can get cherry-picked onto branches for releases. So working on cnab-claims 1.0.1, a commit would be merged to master, and then cherry-picked onto cnab-claims-1.0.0-ga before the branch cnab-claims-1.0.1-ga was created.

Thoughts on that? Maybe this nomenclature would just get too confusing.

[chris-crone]

That sounds good to me. I like that the Git actions have spec process meaning.