Multiple APIs in one Sub-project

Owned by Tanja de Groot
Last updated: Apr 24, 2024
4 min read

ARCHIVED

This section has been updates with the outcomes of the dedicated meeting on this topic on 2024-04-12.

Original related GitHub issue:

 Herbert's proposal here: Proposal to establish API Families as Working Groups across API Sub Projects · Issue #7 · camaraproject/ReleaseManagement (github.com)

Issue & proposal

GitHub release packages provide a zip file that includes the full API Sub-project repository 

If multiple API files are managed in one API Sub-project/repo, then release package will include all APIs, even if they are not intended to be released.

Proposal:

1) The notion of API family will not be release managed. CAMARA release management only considers APIs and their releases

2) The proposal is to

  • develop only one API (file) (exception see below) in one API Sub-Project

  • exception: if an API Sub-project wants to keep multiple APIs in the same API Sub-project:

    • all APIs in this API Sub-project shall always be released together

    • all APIs that are part of the release of an API Sub-project shall provide the require release assets.

    • if a different team or release schedule are needed to release one API of a Sub-project that has multiple APIs, then it shall be moved (with its related assets) to its own API Sub-project.

NOTE: We can look at reworking/simplifying the API sub-project repository structure if needed.

Agreement from the team to adopt the "1 API per repo" approach in principle but also more flexibility is introduced by adding the next proposal.



2024-04-12: Additional proposal from Herbert/Shilpa to decouple release name/number from contained API versions 

  • Decouple the (pre-)release tag and package name/number from the API version.

  • Add some addition semantics in the release name/number

See whiteboard session below for examples.

Proposal: 

  • a) Tag, release and repo are coupled

  • b) Release name/number is decoupled from API version

  • Number the releases rx.y; Use r0.y if an API is sandbox-grade and rx.y with x>0 once in meta-release. 

  • Use subsequent numbering of releases across meta-releases (see whiteboard example below).

Agreement from the team to go forward with that decoupling proposal and update the process to reflect it (@ Tanja)



2024-04-12: Additional proposal of meeting participants: 

  • option b) use another naming/numbering schema for the releases of the sub project repositories (note tdg: not sure I understand if this is different from the proposal on the table "rx.y" ?)



2024-04-12: Additional proposal from Herbert to introduce beta releases

In this case:

  • an initial or alpha release is for rapid development 

  • a beta release is stable enough for API implementation & testing

  • a release-candidate only allows for bug fixing

Agreement from the team not fully clear, but will do an update to the process to reflect it (@ Tanja)

Proposed picture update - please comment on arrow labels names:





I had a more complicated version of the previous picture for API versions, but not sure it helps to put this one (and thus to update it to include beta as well.

API Groupings

Grouping of APIs is useful to reduce the number of meetings and reporting load with the increasing number of APIs, and facilitate moving APIs from one family or group to another, or combining related APIs from multiple API Sub-projects into one group.

Proposal

  • group API Sub-projects for meeting / governance purposes (e.g. as current API families, but can also support other groupings).

  • options are 

    1. using a GitHub Working Group folder 

    2. using a CAMARA Wiki page - seems to be the preferable approach as this is also where meetings are now being managed.

Agreement in the team to go forward with the option 2. Tanja will provide an example to demonstrate the proposal realization on the Confluence.

Actions:

  • Each API Sub-projects that contain multiple APIs should

    • decide if it should create separate sub-projects for its APIs

    • If so, decide on the name and request the API Sub-project creation to cCasey & Evan

    • on the API Sub-project pages on the wiki add the list of APIs managed together

    • Create one API release tracker page for each API-Subgroup and its API(s)



WISHLIST

  • ability to create the API release tracker page data by reading a yaml file in the repo. @Tanja de Groot  to investigate - aother are welcome to do so too :-)





Whiteboard example

Potential release sequence for a new project:

r0.1 (release tag only, no release package (repo zip))

  • api1 with v0.1.0-alpha.1

r0.2 (release tag only, no release package (repo zip))

  • api1 v0.10-alpha.2

  • api2 v0.4.0-alpha.1

r0.3 (pre-release with release package) => API implementation for testing - multiple beta releases following feedback 

  • api1 v0.10-alpha.2

  • api2 v0.4.0-apha.2

r0.4

r0.5 (public-release for meta-release - Sandbox)

  • api1 v0.10.0

  • api2 v0.4.0

.....

r1.0 

  • api1 v1.0.0-rc.1

  • api2 v1.0.0-rc.2

r1.1 (public-release for meta-release - Incubated)

  • api1 v1.0.0

  • api2 v1.0.0

.....

Existing in next meta-release

r2.0

  • api1 v1.1.0-alpha1

  • api2 v1.0.0-alpha1

r2.1

  • api1 v1.1.0-rc1

  • api2 v1.0.0-rc1

r2.2 (pre-release)

  • api1 v1.1.0-rc1

  • api2 v1.0.0-rc2

r2.3

...

r2.4 => M5

  • api1 v1.1.0

  • api2 v1.0.1

r2.5

  • api1 v1.1.1

  • api2 v1.0.1



next meta-release

r3.1 

  • api1 v1.1.2

  • api1 v1.0.2

meta-release with breaking changes by Commonalities

r4.1

  • api1 v2.0.0-alpha.1

  • api2 v2.0.0-alpha.1

r4.2

  • api1 v2.0.0-rc.1

  • api2 v2.0.0-rc.2

r4.3

  • api1 v2.0.0

  • api2 v2.0.0



Challenge - can the API tracker info be pulled from yaml file in the repository. To be investigated.