Proposal for the lifecycle of API Repositories with Sandbox/Incubated/Graduated/Archived

Owned by Herbert Damker
Last updated: Aug 22, 2024
7 min read

  • Prepared by @Herbert Damker for the TSC on 2024-08-22

  • Referenced within issue: ...

Changes compared to previous proposal

  • Previous proposal hasn't considered the split between API Repository and CAMARA Sub Projects as introduced with https://github.com/camaraproject/Governance/issues/142

  • Sandbox / Incubated / Graduated will now be defined for API Repositories, not Sub Projects

  • Proposed relation of API Repositories and CAMARA Sub Project

    • Sub Projects are (as currently defined) consisting of one or multiple API repositories

      • the Maintainers of the Sub Project are the union of the Maintainers of the API repositories belonging to the Sub Project

      • existing Sub Projects can maintain a mix of API Repositories on different maturity levels and can either propose new API repositories themselves or accept API repositories as part of their Sub Project

    • NEW: Sandbox API repositories can initially exist independent of a Sub Project

      •  the decision about the inclusion of an API into a Sub Project vs the creation of a new Sub Project to the Incubation, where much more information about the API and already and initial version is available

      • Sandbox API repositories are encouraged to get accepted by existing Sub Projector to build up the necessary prerequisites to be able to apply for the creation of a new CAMARA Sub Project during Incubation 

  • The maturity level of an API Repository should give the audience a clear indication in which life cycle phase the contained APIs are

Open Point

  • How to differentiate in CAMARA GitHub the Sandbox API Repositories from more mature API Repositories (Incubated/Graduated)

  • Proposals are welcome.

Definitions

CAMARA defines four types of API Repositories:

  • Sandbox API Repository

  • Incubated API Repository

  • Graduated API Repository

  • Archived API Repositories

A Sandbox API Repository is meant for the rapid development of a new API proposal through one or multiple initial API versions (0.x.y) until the first public release of an Initial API Version within and under the guidelines of CAMARA. A Sandbox API Repository can be created independent of a CAMARA Sub Project or in context of an existing CAMARA Sub Project.

An Incubated API Repository is meant for the further evolution of an API which has been implemented and launched already by at least one operator, fits into the CAMARA API portfolio and gained sufficient support within the CAMARA community. An Incubated API Repository is overseen by a CAMARA Sub Project. 

A Graduated API Repository maintains a stable CAMARA API which has been widely adopted within the market (e.g. adopted within at least one complete market or #n operators across #m markets - detailed criteria to be defined later). It is overseen by a CAMARA Sub Project and with  mature processes to replace Maintainers and Codeowners within the API Repository.

An API Repository can get archived due to inactivity during the Sandbox phase (e.g. never reached an initial release or a release cycle) or the TSC decides that the API(s) can’t be maintained or shouldn’t be used any longer for valid reasons. 

NOTE: it should be avoided to host APIs of different maturity within the same API repository. New APIs should be proposed as enhancements and developed within a new (Sandbox) API repository and follow the lifecycle below.

Proposal - Lifecycle

Creation of a new (Sandbox) API Repository

The purpose of a Sandbox API Repository is to describe, develop and define the a proposed API openly within the CAMARA community. The creation of a new Sandbox API Repository will be decided by the API Backlog Working Group, based on either a proposal for a new API development from a CAMARA participant or a enhancement proposal from an existing CAMARA Sub Project. The proposal will be presented in a form as defined by the API Backlog Working Group

The decision of the API Backlog Working Group does only ensure that the API proposal fulfils the minimum criteria for a new Sandbox API Repository:

  • The scope of the proposed API and initial use cases are described and fit in general into the scope of CAMARA

  • At least one initial Maintainer and one initial Codeowner (could be the same person) is nominated

The creation of a new Sandbox API Repository does not imply the creation of a new CAMARA Sub Project.

  • A new Sandbox API Repository based on an enhancement proposal submitted by a Sub Project will get part of the proposing Sub Project. 

  • A Sandbox API Repository for a new API proposal is initially independent, but should aim to either get accepted by an existing CAMARA Sub Project or to build up the necessary prerequisites to be able to apply for the creation of a new CAMARA Sub Project during Incubation. 

  • A Sandbox API Repository which is not part of an existing Sub Project will get a Wiki page (in the Sandbox section), a preliminary mailing list, a Slack channel, and (on request) a Zoom meeting for their communication.

A Sandbox API Repository

  • can initially be maintained by a single Maintainer and Codeowner but should aim to win active Contributors and Maintainers from participating companies

  • can work initially without branch protection to allow rapid development (but only Codeowners have write access to the repository, all other contributions have to be done via the Fork and Pull approach)

  • can create (pre)releases of Initial API versions (0.x). The release should come with all release artefacts as defined by the Release Management, but can be done independent of the CAMARA meta-release cycles

  • can participate in a CAMARA meta-release cycle, in this case all release artefacts as defined by the Release Management must be provided at the milestones

  • can release only Initial API versions, but no Stable API versions

  • must apply again with a changed API proposal in case of scope changes

Incubation of an API Repository

An Incubated API Repositories is meant for the further evolution of an API which has been implemented and launched already by at least one operator, fits into the CAMARA API portfolio and gained sufficient support within the CAMARA community. 

A Sandbox API Repository can apply for Incubation during a CAMARA Meta-release cycle, with the prerequisites and steps below. The Incubation of an API Repository will be finally decided by the Technical Steering Committee (TSC) as part of the Meta-release.

Prerequisites:

  • The Sandbox API Repository has released previously an Initial API version released which is implemented and launched by at least one operator

  • The Sandbox API Repository has defined their target version and scope for the release cycle for the defined milestone of the release cycle

  • The Sandbox API Repository has at least three Maintainers (from three different companies) which are actively supporting the development of the API

  • The Sandbox API Repository has  three Codeowners (preferable from different companies), which are ensuring that changes of the API are done according to the CAMARA Governance (based on issues and with reviewed pull requests)

    • This implies that the branch protection rule is activated within the repository

The Maintainers of the Sandbox API Repository apply for Incubation by opening an issue in the API Backlog Working Group. The API Backlog Working Group will do a pre-check on behalf of the TSC about the above pre-requisites and the fit of the API(s) into the CAMARA API Portfolio early within the release cycle based on the available scope, use cases and user stories, documentation and API definition(s)  with the following potential results:

  • For Sandbox API Repositories which are already part of a Sub Project if there are any needs for change identified

  • For yet independent Sandbox API Repositories

    • a recommendation to include the APIs within an existing Sub Project

    • a recommendation to create a new Sub Project which includes the Sandbox API repository, potentially together with other Sandbox API repositories (especially if they have worked together during the Sandbox phase)

  • Objections regarding the prerequisites or about the fit into the CAMARA scope and API portfolio

 The Maintainers of Sandbox API Repository should follow the recommendation(s), and in case of the recommendation to include within an existing Sub Project ask for the acceptance within the Sub Project. As the final decision about the Incubation is with the TSC, the Maintainers can escalate potential conflicts to the TSC for guidance and resolution.

The TSC will decide about the Incubation of a Sandbox API Repository based on the following criteria:

  • The Maintainers of the Sandbox followed the recommendations of the API Backlog Working Group

  • The Sandbox API Repository has participated within the milestones of  the Meta-release cycle and passed the M3 milestone successfully (with an approved release candidate API Version)

    • The target API version can be an Initial or Stable (the Stable API version (1.x.x) should be only used after the Incubation has been decided after the release candidate, for the release candidate still an Initial API version should be used)

    • This implies that for the API all release artefacts required by the Release Management guidelines have been delivered, and the API is aligned with the Commonalities and Identify and Consent Management (ICM) guidelines and artefacts

  • The release PR for the public release is available and ready for approval by the TSC.

With the decision to incubate an independent Sandbox API Repositories a new CAMARA Sub Project will be created.

NOTE: an implication of the new creation rule for CAMARA Sub Projects is that a CAMARA Sub Project has at least one Incubated API Repository with the above prerequisites. The TSC has to decide about existing Sub Projects which not fulfil this criteria (yet).

Graduation of an API Repository

A Graduated API Repository maintains a stable CAMARA API which has been widely adopted within the market. The Graduation of an API Repository will be decided by the TSC.

Criteria will be defined later. Potential criteria for Graduation could be:

  • the API Repository has been participated within two CAMARA release cycles with a Stable API version

  • the Stable API version has been implemented within at least one complete market or #n operators across #m markets

  • the Sub Project  has mature processes to replace Maintainers and Codeowners within the API Repository based on merits

Archiving of an API Repository

An API Repository can get archived due to inactivity during the Sandbox phase (e.g. never reached an initial release or a release cycle) or the TSC decides that the API(s) can’t be maintained or shouldn’t be used any longer for valid reasons. 

Archiving of an API repository will be decided by the TSC based on a review.

The review will be triggered by (not exhaustive):

  • Inactivity within a new Sandbox API repository

    • three months (no contributions of documents or API specs)

    • no release of an Initial API version after six month

  • Lack of participation of a Sandbox API repository within two consecutive CAMARA release cycles

  • Lack of participation of an Incubated or Graduated API repository within a CAMARA release cycle if there would be changes necessary to stay aligned with the CAMARA Guidelines

APIs within Archived API Repositories are not considered as CAMARA APIs. An archived API repository can get reactivated through a new API proposal within the API Backlog group (e.g. if the original API proposal owner got inactive). If there were reasons beyond inactivity for the archiving, the new proposal should address them, and the decision for reactivation has to be taken by the TSC.