...
Proposals to close the existing issues are provided here: Open Issues Consolidated
alpha API version representation in GitHub
How should alpha API versions be managed in GitHub ?
Alpha API versions are not considered as pre-releases, only as intermediate versions of an API under development. Hence there is no GitHub release package required for an alpha API version.
Options (please, GitHub experts, chime in as I am not a GitHub guru)
- only add an alpha tag on the main branch (vxalpham for API version x.y.z-alpha.m); the next alpha version is a different tag - no branch, no GitHub release package.
- create a separate branch for alpha API versions - no GitHub release package
- other ?
Development branches may be created and are merged into main after approved PRs:
- when is the alpha tag put on the main branch ?
If alpha API version branches are used, when do they get deleted ?
Multiple APIs in one API Sub-project
Issue:
if multiple API endpoints are managed in one API sub project but in separate OAS definition files, each endpoint can evolve separately, but the release packages will mix-up the release of evolutions of these API endpoints.The proposal is to put
Proposal:
Put each API endpoint in its own API sub-project such that individual release packages can be created for each API endpoint.See also Herbert's proposal.
Proposal:
- Request API projects that contain multiple APIs to create separate sub-projects
- Add a confluence page linking the APIs of the same "family" to the CAMARA wiki.
Details:
The notion of API family will not be managed as part of release management. CAMARA releases only consider API versions.
It is recommended to have one API per API sub-project to facilitate the release management and versioning of APIs.
If multiple API are managed in one API Sub-project, each API file shall have its own folder, such that release packages can be created with a focus on a specific API. The API name and the API version of this API shall be used in the naming of the API version tag and API version release package. However, as the release package will also include all other APIs of the Sub-project, this may lead to confusion.
An API Sub-project may also decided to release all APIs in the same API family always at the same time with the same API version. In this case,
- all API files in the release must have the same API version.
- instead of the API name, the API Sub-project name shall be used in the API version tag and the API version release package name.
If later on one API of the API family requires a separate evolution with its own version number, then this API shall be put in its own API Sub-project.
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.
This will 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 APIs from multiple families into into into family.
See also Herbert's proposal here: Proposal to establish API Families as Working Groups across API Sub Projects · Issue #7 · camaraproject/ReleaseManagement (github.com)