API Sub Project Maturity Levels

UNDER DISCUSSION IN TSC

API Sub Projects are used to develop and support releasing APIs.

  • One API Sub Project ideally contains one API or a small set of closely related APIs.ย 

  • A release includes all the APIs of the API Sub Project.ย 

  • Hence a public-release can only be created when all APIs in the API Sub Project have at least an initial public-release API version.

API Sub Project maturity level

API Sub-projects may have one of the follow maturity levels:

  • Sandbox

  • Incubated

NOTE: Graduated level is for further study.

By default an API Sub Project has the Sandbox maturity level.

An API Sub Project needs to minimally respect the following requirements to obtain the Incubated maturity level:

  • It participated in at least 1 meta-release cycle

  • It is managed through regular scheduled meetings with meeting minutes being provided.

  • It has adopted LF tools (Zoom, wiki, ...) and uses them according to the CAMARA guidelines.

The maturity level is determined by the TSC based on these and the below requirements.

Sandbox API Sub Projectย 

A Sandbox API Sub Project can release only initial public-release API versions (0.x.y).

Its released API versions will be listed as part of a meta-release if the Release Process was applied to all of its contained APIs.

Incubated API Sub Project

Incubation is the verification and approval of the Incubated level of an API Sub Project. Incubation can happen as part of a release cycle.

To get the Incubated level the API Sub Project needs to meet the following requirements:

  • The API Sub Project has at least one API released with an initial public-release version (0.x.y)

  • The Sandbox API Sub Project has stated the goal to become incubated in the beginning of the release cycle (on relevant API release tracker pages)

  • The Incubated level is approved by the TSC

An Incubated API Sub Project can manage and evolve in parallel APIs with stable versions (1.x.y) and initial versions (0.x.y).ย 

An Incubated API Sub Projects has to follow the meta-release cycle for all included APIs.

API Sub Project classification (moved from API readiness checklist)

The following table explains each of the criteria to be respected by an API Sub Project to be classified as Sandbox or Incubated.

Status: This table was significantly changed byย @Herbert Damkerafter the May 7th Release Management call ย  - please review and comment

The intention is to bring these criteria into the CAMARA Governance documents.

Nr

API Sub Project classification criteria

Sandbox
Sub Project

Incubated
Sub Project

Explanation



Scope of Sub Project approved within APIBacklog

M

M

For each API, an API Proposal was submitted to the API Backlog working group, and discussed and approved within the API Backlog working group or by the TSC.
Note: Also changes of the initial scope need to be approved by the API Backlog working group based on a new API Proposal or Scope Enhancement issue submitted by the API Sub Project.



Sub Project has at least one Maintainer

M

M

Defined within MAINTAINERS.md file. Note: the first Sub Project Maintainer is typically the API Proposal owner.



Sub Project has Maintainers from at least 3 distinct companies

O

M

Defined within MAINTAINERS.md file. Regarding the prerequisites, role and responsibilities of Maintainers see ProjectStructureAndRoles.md



User stories available for the API(s)

O

Mย (O)

It is recommend to define User Stories for the API(s) within a Sub Project as early as possible. Multiple User Stories per API are recommended to ensure that the developed API(s) is/are generic enough. The User Stories shall use the Userstory-template defined by Commonalities. (Note: within Fall24 meta-release this requirement is optional for non-classified Sub Projects and its APIs which are already launched in production.)



Sub Project has at least one Codeownerย 

M

M

Codeowners will be defined by changes to the CODEOWNER file. Note: Codeowner should be an experienced Contributor and maybe also a Maintainer.



Branch protection rules enabled for "main" and "maintenance" branches.

O/M

M

Enabling of the branch protection rules has to be requested by a Sandbox project latest with the first (alpha) release cycle when they aim to get Incubated. At least 2 Codeowners are needed when branch protection is enabled, 3 recommended



At least 2 Codeowners from distinct companies

O

M

Defined within CODEOWNER file. 3 Codeowner are recommended.



Linting rules are enforcedย 

O

M

The linting rules provided by Commonalities must be successfully executed against every Pull Request of the OAS API definition files before the Pull Request can be merged (branch protection is prerequisite for that).
Note: Linting rules can be manually applied before enforcement.



Participation in the meta-release cycles

O/M

M

Sandbox Sub Projectsย 

  • do not need to participate in the meta-release process as long as they only release initial public-release API versions ("rapid development phase").

  • must participate in the meta-release cycle if they want to release a stable API version.ย 

  • must participate in at least one meta-release cycle to get Incubated.

Incubated Sub Projects

  • must participate in the meta-release cycle

  • must adopt the changes coming from Commonalities and ICM in each meta-release cycle

?

Release-candidate API version tested in at least 2 operator implementations

Y

Y

(proposal to delete as this line is included in the API Release Process)



A public-release API version of a Sandbox Sub Project has to be launched by N operators in M markets in production as a prerequisite to become Incubated

N/A

M

Proposed source for this is criteria is the official "Open Gateway public launch status" page. Other sources about public launches will be evaluated by the TSC case-by-case. Note: the values of "N" and "M" need to be further discussed.