How to manage version for a API family release

[bigludo7]

Problem description
In the context of the Device Location API family we have several API (Yaml). One API for checking location, another for retrieving location and a third soon to be delivered for geofencing.
We wanted to manage release management at the family level as we have to provide consistency between the family.

Using numerical version for the family seems to us not a great idea as it will bring confusion - indeed, the Family in v0.2 will cover this API in v0.3, the other API in v0.2 and the third API in v0.1. Confusing right?

Perhaps have a name for a family version should be better but as this issue will come in several project we need to have a global common naming. Could the name of the family and then a release name using a word following alphabetical like Device Location family - Release Avocado, Device Location family - Release Banana, etc...

Expected action
Have a common agreement on API family release management

Additional context
Need to discuss if we manage this family stuff for one api family. I do not have clear idea on this as consistency is always good but not sure of the value of the family release in this case.

[jlurien]

Another option is to label Releases using some date convention, e.g. Release 2023-09, 23.09...

[bigludo7]

I'm fine with using the date convention.... as long as we can clearly distinct yaml version from the family release version it works for me :)

[shilpa-padgaonkar]

@bigludo7 Do I understand this right, that you would like to change the current release number V0.1.0 to something like Device Location family -Release Avocado or Device Location family -Release 2023-09?

[bigludo7]

@shilpa-padgaonkar I'm not sure we have "Family" release number as of now.

I do not want to change the API version.

But as we have 'family' release we should have a way to identify them. A family release is a set of API (in a version) consistently aligned. Using numerical version for family release will be confusing with API version. The proposal here is to use a name or a date to identify API family release.

For example:

Device Location API family - Release 2023-10 features;

• Retrieve location in v0.1
• Verify Location in v0.2

Device Location API family - Release 2024-01 features:

• Retrieve location in v0.1
• Verify Location in v0.3
• Geofencing in v0.1

This is perhaps specific of the device location where we have several API and we have to consistently align them. We can quickly discuss this on next Commonalities meeting.

[FabrizioMoggio]

there is the same issue with the Edge Cloud API Family. Actually I see a value in using the Family name in the "release tag" for a branch (https://github.com/camaraproject/Commonalities/blob/main/documentation/Camara_Versioning_Guidelines.md). So the Release Tag can be "Family Name - vx.y.z" while inside the branch we have the different APIs with different versioning ("version" field in the YAML file).

I don't see any need to overcomplicate the tag using the the term "release" or adding the year.

For example:

"Release tag" for the branch: "Edge Cloud - v1.0.0"

the branch includes:

TrafficInfluence.yaml: version: 1.1.4 (this is not a tag, this is written inside the yaml file)
SimpleEdgeDiscovery.yaml: version: 1.0.2

[bigludo7]

Thanks @FabrizioMoggio for pointing this document.
So we have a guideline and probably we have to stick to it.

I'l still uncomfortable about using number version for Family as it is confusing with the API version themselves but if I'm the only one I have to live with that ;)

[jlurien]

To me it is also confusing to see v1.x, v2.x for Releases containing APIs in v0.x. Maybe in EdgeCloud could makes sense if the APIs are already v1, etc. In other WGs, that gives the impression to be major releases, while they are really some intermediate milestones towards first major Release. About using the term "Release" as part of the tag, I don't mind using another convention.

[rkandoi]

In the Ericsson view, using semver for groups of API endpoints is not meaningful and may even be misleading (since semver doesn't really give any further information of what has changed). As proposed above, a date convention, or a quarter+year, or even simply a sequential numbering are enough without tying any specific semantics to the "group version" and instead just reasoning about it as cadence.

Added this comment here for completeness and the same has been mentioned in the "consolidation issue" #9.

[tanjadegroot]

The release management process decouples the release numbering from API versioning. A release is done at the level of a repository. If there are several APIs in a repository, it can only be release if all of the APIs have at lease an initial API version (no WIP).
The related discussion on changing the notion API family to become a working group with associated API repositories which can be release separately (above issue #7) is moved to the backlog of the Governance group as camaraproject/Governance#135

[tanjadegroot]

Closed with the API Release Process (see above comment) and per https://wiki.camaraproject.org/display/CAM/2024-05-14+Release+WG+Minutes