Proposal for new API Project lifecycle approach (Sandbox + Incubated)

[hdamker]

Problem Statement

Currently we have within CAMARA only two states defined for the development of APIs:

• API Proposal (submitted within API Backlog)
• Approved API Sub Project (after recommendation of API Backlog Working Group)

With that there is a need to have a relativ high barrier for the approval of a new API Sub Projects to limit the number of API Sub Project which need to be managed and supervised. That has to happen at a point of time when relativ few details about an API proposal are known. There is e.g. the proposal to require three supporting companies for a new proposal - due to the early state of a proposal it is difficult to get such commitments.

Solution Proposal

Introduce two different lifecycle states for an API Sub Project:

• Sandbox Sub Project
• Incubated Sub Project
• (Graduated Projects can be introduced later as well, but are not subject of this proposal)

Principles:

• Easy entry into CAMARA for new proposals, low barrier to get a “sandbox” to develop a proposed API and to attract (additional) contributors and implementor (= operators) for it.
  • A Sandbox Sub Project can be created after short evaluation that an API Proposals fits into the defined scope of CAMARA
  • Alternatively a new API proposal may get adopted by an existing Sandbox or Incubated project
• Deeper evaluation and clear criteria for the step from “sandbox” to “incubated”
  • Need to be done only for the API sub project which are already aiming to get "incubated"
• Clear separation of sandbox API projects from incubated API projects needed
• A Sandbox Sub Project can release only initial API versions (v0.x.y)

Criteria for a Sandbox Project to get "incubated" (draft):

• Linting rules enabled
• Protected branches enabled
• Follow design guidelines from commonalities and profile guidelines from icm
• Maintainers doc ( with at least 3 maintainers from distinct companies)
• Codeowners doc (again at least 3 from distinct companies)
• Participated in at least 1 release cycle
• Project schedules regular meetings with MoMs being written
• Project has adopted LF-tools (Zoom, wiki...)
• API versioning and repo release naming conventions are followed.

Expected Actions

The TSC should kindly discuss the proposal as an alternative to #122. If adapted:

• the Checklist for Incubation has be codified within the ProjectStructureAndRoles (some criteria could be integrated into API version criteria)
• the API-onboarding process description has to be rewritten
• a proposal how to separate Sandbox from Incubated projects need to be discussed with LF
• the Release Management Group should differentiate the release cycle for Sandbox and Incubated projects and use the notion of "initiale" and "stable" API versions
• New API sub project will be created as Sandbox projects. Existing API Sub Project should evaluated themselves if they aim fulfill all criteria for incubation during Fall24 release cycle (= they will be evaluated by the TSC during the release cycle). Alternatively they can participate as Sandbox Project and aim for an initial release within Fall24.

[hdamker]

As presented within TSC on May 16th:
TSC_2024-05-16_Sub Project Lifecycle.pdf

The proposed criteria are currently available within https://wiki.camaraproject.org/display/CAM/API+Sub+Project+Maturity+Levels

Please leave your comments here.

[TEF-RicardoSerr]

On the mean time that a decision is taken, it is needed to define which APIs are suitable to be sent for aproval to TSC (from the API Backlog).

Proposal is to have at least 2 companies supporting them (API owner + additional supporter) this is in order to ensure that the subgroup can work properly (one company propose PRs so the other one may approve them) as it is required regarding the minimun GitHub Workflow

Ref. #122

[eric-murray]

I support some form of labelling in the GitHub repository to distinguish the more mature sub-projects from those that are just getting started or have not made much progress. Whilst there are clues to be had from GitHub itself (number of contributors, number of commits, etc.), clear labelling would help external viewers to focus on the more "important" of CAMARA's activities.

And for sure we need clear criteria to move from "Sandboxed" to "Incubated", and I broadly agree with the above proposals.

My comments are:

• I think this needs to be directly linked to a GitHub repository so that it can be labelled (possibly using topics as is done for working groups). So a sandboxed API must have its own repository, even if part of a larger family. I don't see this working for repositories that include several APIs, unless all have the same status, but even then you would have an issue carving out APIs to a separate repository if one wanted to become incubated but not the others.
• We might want to distinguish between APIs that are just getting started, and those that have not made any real progress over a period of time
• I'm not so sure that the term "Sandboxed" will be understood by all external observers of CAMARA. It might be interpreted as "experimental", "temporary" or even "unimportant". Some thought should be given to the label so that early APIs are not unduly dismissed by those that might want to contribute to or use such an API.

[jgarciahospital]

Agreed that labelling would help understanding the status of each subgroup, differentiating just created groups from those that are much more advanced (with stable releases available, for example). Agree Eric that dedicated sandbox WG is not convenient, neither the usage of "sandbox" name.

That system will allow a subgroup to be slowly starting, until scope is clear, user stories... and then evolve to a issue/PR based discussion where surely more companies will participate. But a dedicated subgroup per API (or family, as currently) still need to apply, avoiding re-working when migrating from one status to other.

But, in any case, the issue remains. Which rules are to be set for a group to start? Physical limitation is 2 companies, for the PRs to be approved. Do we all agree to maintain that as a base for a subgroup to be created, and to try to specify a labelling system to separate the phases of the groups?

• New Subgroup: Support of 2 or more companies. Approved in Backlog
• Existing Subgroup enhancement (same API or new in the family): Lazy consensus in Backlog, and acceptance in the affected subgroup.
• Subgroup evolution: Labelling with specific rules to identify the current evolution of the group, e.g. scope definition, alpha version, maintenance... Evolution process to be defined

[lbertz02]

Are 2 companies (one company propose PRs so the other one may approve them) actually required for minimum GitHub Workflow or is the minimum GitHub Workflow something defined within CAMARA (looking for a reference)?

[hdamker]

Are 2 companies (one company propose PRs so the other one may approve them) actually required for minimum GitHub Workflow or is the minimum GitHub Workflow something defined within CAMARA (looking for a reference)?

@lbertz02 Technically: We are protecting the main branch so that at minimum one Codeowner review is needed to be able to merge a PR (and no direct commits allowed into main). If one of the Codeowners is opening a PR there must be at least a second one to approve. But that's only the technically minimum. The process for "Changes and contributions to CAMARA" is described within ProjectStructureAndRoles.md and has more requirements.

[lbertz02]

@hdamker Thank you. There in Step 4 of "Changes and contributions to CAMARA" is the statement that it is ideal for multiple companies to be involved - not required. I agree that it is ideal but it is important to note that it is not currently required unless I missed other text.

[hdamker]

... There in Step 4 of "Changes and contributions to CAMARA" is the statement that it is ideal for multiple companies to be involved - not required. I agree that it is ideal but it is important to note that it is not currently required unless I missed other text.

@lbertz02 There is an indirect requirement, as we currently require to have Maintainers from at least two companies before we create a Sub Project. They shall be invited to the review (but yes, they don't need to make a review/approval - silence is agreement).

[hdamker]

I'm closing the issue as it is now replaced by #159. Thanks a lot for the comments and I invite everyone to continue it based on the updated proposal in #159