Align also Working Group release numbering with the rx.n numbering schema starting in Spring25 cycle

[hdamker]

Problem description

Within Fall24 release cycle it was sometimes confusing that the Commonalities and ICM had release number rx.y.z and version numbers vx.y.z which even "equal". With this special schema it is also not possible that a working group has artefact with different version numbers (e.g. Artefacts with x.y.z and some new document/template etc with an 0.x.0 number)

Possible evolution

Decouple also for Working Groups the release numbers from the version of the artefacts and use the same release numbering schema, starting with r2.1 for the first release with alpha versions for Spring25. Update the documentation accordingly.

Note: Commonalities and ICM can still state that all artefacts (or documents) within the release have the same version number (e.g. 0.5.0 in case of Commonalities). But there could be also other artefacts like the templates which have own version numbers (and will be patched/maintained independently).

Alternative solution

Additional context

[eric-murray]

@hdamker
You suggest above Commonalities and ICM should start with r2.1 Spring 25 meta-release, but I had understood (for APIs) that the first version using the rx.y notation should always start r1.1, irrespective of which meta-release cycle it was targeting.

So does the proposal remain that Commonalities and ICM start at r2.1 for Spring 25? Or should they follow the API rules, and start at r1.1 for Spring 25?

[hdamker]

@eric-murray I get the point, within the above proposal I've assumed that there is a relation between the x in rx.y, which is not the case. But here we have still both options, for another reason:

a) considering the releases of Commonalities and ICM within the Fall24 meta-release as the series of r1.x releases (potentially even adding the tags to the releases and at some points in documentation) => continuing with r2.x
b) start with the Spring25 release cycle => start now with r1.x

Propose to discuss that in today's Release Management call
cc: @tanjadegroot

[tanjadegroot]

Sorry for my late reply: I would argue we can make an exception and start with release 2.1, given that we have had a first public release of both Commonalities and ICM, but that the release numbering was not yet defined as needed (so consider it as a RM bug). I think logically for people it makes sense to have the next release be r2.1.

[tanjadegroot]

For artifacts inside Commonalities or ICM that may have their own version, would the following be useful:

• If an artifact change impacts the APIs, then the repository version should also change accordingly (MAJOR, MINOR, PATCH), and a new release shall be created.

• If no existing API impact, then such changes can be done outside a release with their version being changed inline with semver guidelines, and they shall be reflected in the CHANGELOG. The changes shall be included in the next release, but the advantage is that they would be available in main after each such update.

An example of the latter could be the update of a template that has its own version that does not impact APIs.

Overall, I am not sure that separate artifact versions would need a different release handling. Any updates would be part of the preparation of the next release. The artifact version can be updated as needed, but would just be part of the release assets in the next release.

The question is: do we want to put a version number in each GitHub based document or can we update the VERSION file according to the changes made to the document (which would show there were updates from the last official release ? or just put wip in the VERSION file here as well as soon as a first change (PR) is made ?

I think this last point is probably easiest as the actual changes can be seen from GitHub PRs anyway.

[hdamker]

Are the above points documented in the process documents? @tanjadegroot ... if yes we can close the issue.

[tanjadegroot]

@hdamker I have added a section "Additional versioning of artifacts" with the above information here: https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/14551399/Meta-release+Process#Version-and-release-numbering.

Please check if OK

[hdamker]

https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/14551399/Meta-release+Process#Version-and-release-numbering.

I'm not really sure if additional artifacts should be versioned outside of releases, or in other words if we really need here a different approach then for API definition files in API repositories. As long as the repositories are not tagged with a release number it is difficult to unambiguously refer to a certain version. I would rather see a patch release (potentially in a maintenance branch) if an artifact has been changed. If the release frequency of some artifacts is decoupled from the working group repository, a separate repository might make sense.

[tanjadegroot]

proposed new text:

Some assets inside Commonalities or ICM may have their own version embedded. As long as their repository is not tagged with a release number it is difficult to refer unambiguously to a certain version of its assets.

To manage changes of such versioned assets, the following versioning guidelines are provided:

• All versioned assets are to be handle in the same way as API yaml file versioning (alpha, release-candidate and public versions), and shall be released though subsequent repository releases.
• A patch release of the repository (potentially in a maintenance branch) can be created if an asset need to be changed after public release.
• If the release frequency of some assets is too different from the rest of the working group repository, a separate repository may be created for managing and releasing that asset.
• The version of the assets that do not contain their own version is the version documented in the VERSION.yaml file.

Note: Eventually it is recommended that all release assets include their own version, such that the VERSION.yaml file can be removed. The exact documentation of those versions is to be determined. This shall be realized latest by the stable version of Commonalities and ICM.

The above update is here: https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/14551399/Meta-release+Process#Version-and-release-numbering

If this text is OK, we can close this issue.

[hdamker]

The proposed new text looks good to me, just corrected two typos directly on the page.

[tanjadegroot]

Thanks, so then this issue can be closed as completed.