READY FOR REVIEWUNDER DISCUSSION IN TSC
API Sub -projects Projects are used to develop and support releasing APIs.
- One API Sub -project Project ideally contains one API or a small set of closely related APIs.
- A release includes all the APIs of the API Sub -projectProject.
- Hence a public-release can only be created when all APIs in the API Sub -project 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 statuslevels:
- Sandbox
- Incubated
NOTE: Graduated level is for further study.
By default an API Sub -project Project has the Sandbox maturity statuslevel.
An API Sub -project Project needs to minimally respect the following requirements to obtain the Incubated maturity statuslevel:
- 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 status level is determined by the TSC based on these and the below requirements.
Sandbox API Sub
...
Project
A Sandbox API Sub -project 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 status level of an API Sub -projectProject. Incubation Incubation can happen as part of a release cycle.
To get the Incubated status level the API Sub -project Project needs to meet the following requirements:
- The API Sub -project Project has at least one API released with an initial public-release version (0.x.y)
- The Sandbox API Sub -project Project has stated the goal to become incubated in the beginning of the release cycle (on relevant API release tracker pages)
- The Incubated status level is approved by the TSC
An Incubated API Sub -project 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 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 Project to be classified as Sandbox or IncubatingIncubated.
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 | Incubated | Explanation |
Linting rules enabled
The linting rules provided by Commonalities that are successfully executed against the OAS API definition file. The output report of the linting shall be provided.
Maintainers (from at least 3 distinct companies)
This needs to be checked and confirmed by the API Sub-project team in the API Sub-project home/MAINTAINERS.md file.
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. | |
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 |
This needs to be checked and confirmed by the API Sub-project team in the API Sub-project home/CODEOWNERS file.
?
API release numbering conventions
This is verified using the information on the release tracker page.
Protected branches enabled
Do we still need this ? As there are no more release publication branches, this would only apply to maintenance release branches ?
?
Release-candidate API version tested in at least 2 operator implementations
References to at least 2 operator implementations of the API are provided. In which form shall this information be provided ? Links to websites could be added to the API release tracker.
?
initial public-release API version certified and launched in at least 2 operators is needed to become stable
References to at least 2 certifications and at least 2 commercial operator implementations of the API are provided. In which form shall this information be provided ? Links to websites could be added to the API release tracker.
The following table is the API readiness checklist of the assets that need to be provided for the release of an given API version.
Nr
API release assets
alpha
release-candidate
public-release
initial
stable
Linting rules enabled
Y
Y
Y
Y
Maintainers doc (from at least 3 distinct companies)
Y
Y
Y
Y
Codeowners doc (from at least 3 distinct companies)
Y
Y
Y
Y
?
API release numbering conventions followed
Y
Y
Y
Y
Protected branches enabled
Y
Y
Y
Y
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). | |
Participation in the meta-release cycles | O/M | M | Sandbox Sub Projects
Incubated Sub Projects
| |
|
|
N
|
|
?
(proposal to delete as this line is included in the API Release Process) | |
A public-release API version |
N
N
N
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. |