ICM Release Versioning

[eric-murray]

Problem description
The current proposal for the "name" (i.e. version) of the next Identity & Consent Management documentation release is "0.3.0". The issues with using full semantic versioning for this documentation are:

• Using semantic versioning with major version 0 rather begs the question as to when the documentation will become "stable". There are no agreed criteria that would result in a major version bump.
• The release is a set of documents and artifacts that may have their own separate release number. Using semantic versioning for both the release as a whole and documents within may cause confusion if and when these version numbers diverge.

Expected action
Herbert has made a proposal in Release Management to adopt the same release notation as is used for sub-projects, decoupling the release version number from the separate version number (if any) of the included documents and artifacts. If this proposal was adopted, then the next release (likely an "alpha") would be named r1.1, with subsequent versions resulting in a minor version bump until the final version for the next meta-release is declared.

This proposal should be discussed within ICM and the conclusions fed back to Release Management

Additional context
API (sub-project) release numbering rules are documented here

[jpengar]

@hdamker 's proposal seems good to me. It would be a matter of seeing what version we put on existing documents (I suppose initially v0.2.1 for all of them) and how we mark that version (in the filename? in the document content? both?...).

[eric-murray]

Apparently the first release using the rx.y notation should always be r1.1, irrespective of what has come before. I updated the issue description.

[jpengar]

@camaraproject/release-management_maintainers Is there a conclusion about the versioning we need to use in the ICM WG for the next Spring25 alpha release? Is it r1.1?

What version we put on existing documents (I suppose initially v0.2.1 for all of them?) and how we mark that version (in the filename? in the document content? both?...)

[rartych]

Currently proposed guidelines are documented here:
https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/14551399/Meta-release+Process#Version-and-release-numbering

version is documented in a dedicated file “VERSION.yaml” in the home folder of the repository

If you have any questions or remarks for that guidelines, do not hesitate to add your comments inline.

[jpengar]

Currently proposed guidelines are documented here: https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/14551399/Meta-release+Process#Version-and-release-numbering

version is documented in a dedicated file “VERSION.yaml” in the home folder of the repository

If you have any questions or remarks for that guidelines, do not hesitate to add your comments inline.

According to the documentation Version and release numbering follow separate schemes. A given release concerns a specific version of the released artifacts., but as far as I understand, there is a common version for all artefacts/documents of the WG (ICM in this case), right? There is no specific independent versioning for each artifact/document. e.g. https://github.com/camaraproject/ReleaseManagement does this.

[tanjadegroot]

Sorry for my late reply:
On the release number to use for the next release:

I would argue we can make an exception and start with release 2.1, given that we have had a first public release ICM already when the release numbering was not yet defined. I think logically for people it makes sense to have the next release be r2.1.

[tanjadegroot]

On the version to put in the VERSION.yaml file:

This file would hold the version valid for all assets in the repository. An API that is aligned with a given release is so for the indicated versions of the assets of that the released repository.

If one or more asset carries its own versioning information in addition to the repository version, the asset's versioning does not necessarily need to have the same version, but it's versioning scheme needs to be updated inline with the versioning of the repository in terms of MAJOR, MINOR or PATCH updates.

Can you provide an example of an evolution of an asset that would would evolve independently without impacting the documentation in the repository ?

[jpengar]

Can you provide an example of an evolution of an asset that would would evolve independently without impacting the documentation in the repository?

Actually, I don't have an example for ICM. I don't think we have that requirement in this WG. I don't mind having a common version for all artefacts/documents, I just wanted to understand the current RM definitions. Thank you @tanjadegroot for your answers.

[jpengar]

https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r2.1