Consolidation Issue for open points release management

[shilpa-padgaonkar]

Problem description
Currently, there are several open issues (7 in total) which touch the topic of release management, and some are even duplicates.

Expected action
This issue will provide a consolidated view of all open issues for release management under commonalities. This will help the TSC to address the topic in a more structured way.

Under this issue, contributors are also requested to nominate themselves if they would like to participate in the release management concept work that will be undertaken in the TSC. Would be very useful if you could also specify if you wish to be an active contributor or just a reviewer, or both (depending on your interests and the time you can spend on the topic).

Additional context
Current open issues and categories:

1. API Versioning (Alpha/Beta vs Semantic...)
   Consider including Alpha and Beta labels to API versions #13
   API Versioning - Aggregation #14

2. API Family versioning
   How to manage version for a API family release #12

3. Release Branches
   Development and Release Branches #10

4. API Release 1.0 and general conformance
   Readiness Checklist step 6 update proposal #16
   Define mandatory end points URL in each project Governance#141
   Add guidance for Info object in apis Commonalities#201
   Automate API design tests to ensure CAMARA compliance Commonalities#200

5. Camara-wide release
   Though there are no open issues on this topic, it has been discussed on several occasions in commonalities.

[rkandoi]

Do you think this PR is potentially related to this topic as well - Define mandatory end points URL in each project
camaraproject/Governance#63?

My thinking is that it could be since it is related to "conformance" - i.e., when is an API conformant if it only implements a subset of the endpoints? What should be the behaviour when not all endpoints are implemented.

[hdamker]

Thanks @shilpa-padgaonkar! I volunteer to contribute and review ... it's a very important topic for CAMARA.

Another issue with input the topics 1-4: #5. Another point to add would be "Step-by-step instructions to create a release within a sub-project", plus potential tooling to automate/enforce these.

[Kevsy]

Thanks @shilpa-padgaonkar - also related,

Governance#95: Automate API design tests to ensure CAMARA compliance

[shilpa-padgaonkar]

Some questions derived from the issue consolidation:

1. Do we need a Camara wide release? If yes, how often?
2. Do we need another explicit API Family versioning?
3. API versioning: Semantic versus Alpha-Beta style
4. What are the important aspects to decide Camara conformance?

Please feel free to extend this list

[bigludo7]

Thanks @shilpa-padgaonkar
Completely aligned to prepare this discussion.

I'm fine with this list. The Camara Conformance is a huge topic and perhaps we have to split it in several pieces:

• What will be targeted to conformance (endpoint ? attribute?)
• How we describe this conformance (test collection? md document?)
• How we loop with Open Gateway Product stream ? We should agreed conformance with them when they were at the origin of the API.
• How we loop with GSMA that will 'run' effectively the conformance test?

[Kevsy]

I agree @bigludo7 -

How we loop with GSMA that will 'run' effectively the conformance test?

I would just say 'How we align with GSMA certification', which are additional tests.

CAMARA releases should be automatically checked (GitHub Actions) for OAS 3.0.x conformance, conformance against a linting ruleset based on Commonalities API Design Guidelines, and (I think) a 'Security by design' check which can detect intrinsic vulnerabilities.

Then when the API is implemented, the GSMA certification tests can check that the implemented API matches the CAMARA release, and other tests (including performance) that may be required.

[tanjadg]

On the fact that we are planning to do release mgmt for "API families". Unless there is any specific advantage to do this,
I think we should not mix working groups with release mgmt. Working groups is about the definition of the API. IMHO only the outputs of teh work groups should fall under release mgmt (especially as API families are sort of "arbitrary, can change name, etc.). and it adds a level of complexity.

Also what would be the criteria to do a "CAMARA wide release" ? is it to release every e.g. 3 months the latest version of all stable APIs. ?

for an example look at the 3GPP API forge - especially the readme part, and maybe discuss with the person doing the maintenance as it is quite well done IMHO, and including the automated linting pipeline etc.. - see https://forge.3gpp.org/rep/all/5G_APIs

[rkandoi]

Signing up as an active contributor to this work item (based on Shilpa's request to make an explicit note).

[chrishowell]

Yes please add me to 'active contributor' :D

[murthygorty]

Hi @shilpa-padgaonkar , great initiative to start this structured way of addressing - thank you!
I would like to be a reviewer for 'API Release 1.0 and general conformance' section please - this is a huge topic in of itself and a good one.
cc: @gmuratk

[shilpa-padgaonkar]

Casey from LF has created a group for release-management https://lists.camaraproject.org/g/release

Kindly subscribe to this group if you are interested in the release management topic. There is a plan to have dedicated sessions arranged for this topic.

[hdamker]

5. Camara-wide release
Though there are no open issues on this topic, it has been discussed on several occasions in commonalities.

There is no issue for that, but already a paragraph within the ProjectStructureAndRoles.md:

Each Sub Project shall have a release management. The release cadence shall be determined by the TSC and on a regularly published schedule. Milestones shall be set up within each Sub Project to ensure the ability of each Sub Project to meet the release schedule as defined by the TSC.
Goal is that all Sub Projects updated are released at the same release milestone so that the implementors of the APIs become accustomed to the regular release cadence.

[rkandoi]

Sharing here Ericsson’s current thinking on some aspects of this topic. This thinking is based on the discussion in TSC on Oct 19, 2023 (PR to minutes of meeting). This input could be considered by @hdamker / DT when preparing the release management proposal.

• We think applying semantic versioning (semver) at the “endpoint / API” level makes perfect sense but semver at API Family / CAMARA APIs is not needed.

  • We do not understand what benefit versioning “API Family” brings. In fact, we think applying semantic versioning to the “API Family” or “CAMARA APIs” is misleading. The rationale for this is, on this "group" level, using semver provides no additional information about what has changed in the underlying specifications. Perhaps a date / quarter+year / or simply a sequential number approach makes more sense to version "grouped" things for periodicity / marketing purposes. (Note that this thinking is largely aligned with @tanjadg’s view above).

• As the TSC MoM notes, the notion of an “API Family” is confusing. While discussion the topic, it became obvious that even the notion of an “API” is currently not formalized in CAMARA and is used differently by different API subprojects. It would be good to formalize with some written text what we mean by an API.

  • In our best understanding, an “endpoint” is an API that will have semver based versioning. And the characteristic of the endpoint is that the “top-level” / “base path” name is unique across all CAMARA APIs.

• We agree with the TSC proposal that there are either “released /stable” APIs or “work-in-progress” APIs (and here we mean the specification part of the work – see below for more). Hence, we do not need alpha / beta etc. in the versioning phases. The current proposal suggests using “alpha” to denote the “work in progress” status. We have seen that some API subprojects are using “wip” instead of “alpha” which is more reflective of the situation. While result would be the same regardless of “wip” or “alpha”, we prefer “wip”.

• What is a “release” and when does it occur? Semver tracks major/minor changes since recent released state – therefore, knowledge of what released and when as well and when next release will happen is very important for API versioning.

• Once the API subproject “releases” a (candidate) version, it then must go to the “readiness tests”. There could presumably be error corrections that are identified during the tests. A mechanism for error correction would be ideal to setup already in the beginning. Perhaps in addition to “wip” stage, we also need an “rc” phase?

• Should CAMARA also propose a deprecation policy for the versioned API endpoints. If over time, an API has 3 or 4 or 5 versions and different providers implement different versions, it would make interoperability a big challenge. This could presumably be solved by specifying a minimum/maximum number of allowed parallel “stable versions” as well as guidelines for duration on deprecation.

• We think periodic CAMARA level releases make sense for two reasons – one to set a cadence for the various working groups and second for marketing purposes. The comment/link above from @hdamker seems to echo this view (link. 3GPP seems to work in a similar way and some of those learnings could be adopted in to CAMARA. Linux foundation may have its own mechanisms which could be explored too.

[mhfoo]

Pls include me; representing the private repo project.

[hdamker]

There is now the new repository https://github.com/camaraproject/ReleaseManagement as agreed within the last TSC meeting. To collaborate there on Release Management for CAMARA and its sub projects kindly subscribe to the mailing list https://lists.camaraproject.org/g/release, e.g. by sending a mail to [email protected]

Consider also to volunteer as a maintainer within the new working group by commenting on #1

[hdamker]

@shilpa-padgaonkar @rartych would it be ok to transfer this issue here over to the new repository? Which other issues should be transfered with it? All the ones listed above?

[hdamker]

@rartych Any update on my question above?

[rartych]

@hdamker I am sorry for lack of earlier response.
I think that all issues labeled with release management label can be transferred to Release Management repository.

[tanjadegroot]

Final status of this issue:

API Versioning (Alpha/Beta vs Semantic...)
#13 - Closed
#14 - Marked as backlog

API Family versioning
#12 - Closed

Release Branches
#10 - Closed

API Release 1.0 and general conformance
#16 - Closed
camaraproject/Governance#141 - Transferred to Governance for discussion
camaraproject/Commonalities#201 - Transferred back to Commonalities with info and closed there.
camaraproject/Commonalities#200 - Transferred back to Commonalities and closed there.

Camara-wide release
Though there are no open issues on this topic, it has been discussed on several occasions in commonalities. - Closed - Meta-release process defined (see issue #4)