...
Multiple APIs in one API Sub-project
Issue:
GitHub release packages include This section has been updates wits 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
- group API Sub-projects for meeting / governance purposes (ex-API families).
- options are
- using a GitHub Working Group folder using a CAMARA Wiki page - seems to be the preferable approach as this is also where meetings are now being managed.
- 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 have the same version and shall always be released together.
- all APIs that are part of the release of an API Sub-project name shall be used instead of the API name in the creation of the API version provide the require release assets.
- if any of the APIs needs to evolve its version to a different version than the other APIs in the same API Sub-project, 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.
Impact on Wiki, could be either:
- Add the API groupings on the API Sub-group page
API Groupings:
The grouping of APIs into families or other groupings, e.g. by related working groups, can be done easily using a CAMARA wiki page.
...
2024-04-12: Additional proposal from Herbert/Shilpa on API version asset naming to
- 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.
Agreement from the group to go forward with that decoupling proposal and update the process to reflect it (@ Tanja)
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 families into into into familyAPI 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
- using a GitHub Working Group folder
- 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)
...
- s
...
- )
Decision point:
- a) Tag and repo are coupled, but decoupled from API version(s) contained in the release
- b) Release of repo name/number is decoupled from API version - just number the releases e.g rx.y 0-n if y and use x=0.y if API not stable; 1.y.z. 0) once in meta-release: next metarelease . use subsequent numbering across meta-releases
Proposal of the meeting participants: option b) - using another naming/numbering schema for the releases of the sub project repositories
Whiteboard example
Potential release sequence for a new project:
...