Removing or changing x-camara-commonalities extension field

[rartych]

Problem description
x-camara-commonalities field was introduced to info object in version 0.4, but it occurs that it is hard to maintain esp. when Commonalities produce patch release.

Expected behavior
Remove x-camara-commonalities field from info object definition in API Design Guidelines.
Release notes and Changelog include reference to the Commonalities release available when API is published.
Additionally, the same information can be mentioned in API Readiness Checklist point 2

Alternative solution
Indicate only Commonalities release major number (r1) or version without patch (0.5).

Additional context

The issue was raised during TSC meeting.

[tanjadegroot]

It could be removed as it is documented in several places as listed above, especially in the API Readiness Checklist.

However, if you want to keep this in the API definition, I think we should do the same as the version in the API url:

• per SemVer: use only the MAJOR version when x > 0 ( so for versions 1.y.z)
• CAMARA exception: use MAJOR.MINOR for x=0 (so 0.y (now 0.5) for versions 0.y.x) where
  • y changes if there are API impacting MAJOR or MINOR changes;
  • z changes when there are non API impacting MINOR or PATCH changes.

This would imply that you do not have to re-release all the APIs if there are non API -impacting changes to the Commonalities assets.

[murthygorty]

Agree, changelog template calls out the version of commonalities and ICM that the API is adhering to.
x-camara-commonalities applied to a prior world when we didn't have current Release Management Standards.

BUT...
I request that we ask the 'Readiness Checklist' to reflect the commonalities version a little more strictly. The checklist guidelines require that "reference" column include the versions, but it doesnt look like our APIs are following it - I checked against the first two API in our homepage, devicelocation and numberverfiication.

cc: @gmuratk

[rartych]

@murthygorty The 'Readiness Checklist' was updated lately, what you have checked are probably checklists used in the previous release:
https://github.com/camaraproject/ReleaseManagement/blob/r1.2/documentation/API-Readiness-Checklist.md

For Spring25 meta-release the new template shall be used and it will be validated by Release Management.

[murthygorty]

@murthygorty The 'Readiness Checklist' was updated lately, what you have checked are probably checklists used in the previous release: https://github.com/camaraproject/ReleaseManagement/blob/r1.2/documentation/API-Readiness-Checklist.md

For Spring25 meta-release the new template shall be used and it will be validated by Release Management.

super, thanks @rartych