Closed hdamker closed 2 days ago
Kevsy
commented
3 weeks ago I agree that it will be useful for the Lead_Repository to store common artefacts for the API Family, including e.g. YAML snippets for common resource definitions, to help ensure consistency across all the related API Repositories. These would be API Family specific and not repeat/conflict with Commonalities.
bigludo7
commented
3 weeks ago @hdamker I'm globally fine with your proposal. Thanks for this !
Few comments:
The MAINTAINERS.md file points to the MAINTAINERS.md file in the Lead Repository
We can have only one file and a pointer? or is it just copying the file? probably I'm enough skilled on git hub capabilities
hdamker
commented
3 weeks ago
- I'm not sure to understand
The MAINTAINERS.md file points to the MAINTAINERS.md file in the Lead Repository
We can have only one file and a pointer? or is it just copying the file? probably I'm enough skilled on git hub capabilities
@bigludo7 The MAINTAINERS.MD file is a markdown file. I thought about a content like:
This API repository is maintained as part of the [<§subprojectname§> API family](https://github.com/camaraproject/§subprojectname§). Please find the list of Maintainers within https://github.com/camaraproject/§subprojectname§/MAINTAINERS.MD
This can be pre-filled within a template repository for an API_Repository, just the Sub Project name has to be replaced.
hdamker
commented
3 weeks ago
- The second point is clarification about "OTPValidation", "SIM Swap" and "NumberVerification": for me this is not a family but 3 distinct APIs. We have one meeting for all three because topics are scarce and close but if tomorrow for any reason we have a peak of activity for one of them we can have split call. We have not exactly the same maintainers list (Axel is only present for NV). Did you have another view for these 3?
@bigludo7 I mentioned only an example what would be possible with the approach. If and which existing Sub Projects we might combine into one API Family is a separate case by case discussion and independent of the approach itself. We get just the option.
Further points:
hdamker
commented
3 weeks ago
- last, in the README.md (which is reflected in the confluence wiki) in the Lead_Repository we explicitly indicate reference to affiliate API right ? (simpleEdgeDicsovery is referred in Edge Cloud readme.md file scope)
@bigludo7 Yes, that makes sense. The Lead Repository defines also the scope of the API family and has links to the "family members"
hdamker
commented
3 weeks ago Thanks to @Kevsy and @bigludo7 for the initial positiv feedback and the questions.
Happy to see more feedback from @camaraproject/tsc-participants and the CAMARA community until June 11th (as discussed in the TSC meeting). After that I plan to prepare the PR and would be glad if we need to discuss only the final details on the PR.
jlurien
commented
3 weeks ago The proposal is also fine to me, we can work on the details in the PR and the repository templates (repo naming, structure, etc). Some general comments:
It's good to give flexibility but it's not obvious which APIs to keep in the Lead_repository, or to move to each own API_repository, when the second API comes to a family. For example, for DeviceLocation, decision is likely to keep or to separate all of them, even if location-verification was the initial one in the family. In QoD, we are moving from one to three, being qos-profiles common to the other two, and that one could be kept in the Lead. In the end it will be a subproject level decision, but some guidelines would be useful.
For "Create an API Proposal initially as Sandbox Sub Project and decide only later if and to which API Family it can be belong ("incubating" a Sandbox project is still also an option)" -> Is this creating an API repo without, temporarily, a parent Lead repo? In this case the codeowners and maintainers are kept in the API repo?
jlurien
commented
3 weeks ago I agree that it will be useful for the Lead_Repository to store common artefacts for the API Family, including e.g. YAML snippets for common resource definitions, to help ensure consistency across all the related API Repositories. These would be API Family specific and not repeat/conflict with Commonalities.
Having common artifacts globally and at API family level it would be very useful to avoid duplications and copy&paste mistakes. We have to work on a mechanism to support proper references ($ref) between specs.
ToshiWakayama-KDDI
commented
3 weeks ago Hi @hdamker, all,
Thank you for the proposal. It is also fine with me in general.
I have one question with slight concern. The proposal is to have only one maintainers list (Maintainers.md) for an API Family and more than one APIs in the Lead Repository, I understand.
I wonder if there would be a case where there are some differences between maintainers for a new additional API and the original maintainers for the API Family (Lead Repository), even if the new additional API can be considered as the same API Family in general. In this case, I am thinking, it may be better to have separate Maintainers list (Maintainers.MD) in the new additional API repository, or it would be enough to merge additional maintainers for the new API into the original Maintainers list in the lead repository. Any views for this kind of case? I understand there will be separate codeowners for the new additional API anyway.
Best regards, Toshi
shilpa-padgaonkar
commented
3 weeks ago Thanks @hdamker for creating this issue:
My 2-cents:
"A subproject of the CAMARA Project led by a voluntary group, open to anyone to participate."
This group can ensure alignment, can agree on grouping together meetings, have shared wiki pages if needed etc. This kind of grouping and alignment, in order to scale, surely brings value.
Fully support the idea that a repo will only host a single API or very closely related APIs as was agreed in release mgmt.
IMHO, there is no need to have a concept of lead and child repos. I see more flexibility if we simply state that a subproject oversees/groups a certain X set of repo/s together. A subproject simply oversees and groups the repos for alignment and efficiency. We do not differentiate further one repo from another by giving them a category like lead or child within this subproject.
Each repo will have its own maintainers and codeowner files (and it is very likely that most names will be the same). The "subproject maintainers" will be a union of all the maintainers from its group of repos.
bigludo7
commented
3 weeks ago @hdamker we have in Device Status subproject probably same "problem" than for device location as commented by @jlurien
in Device Status we have 4 APIs: roaming-status, reachability-status, roaming-status-subscription, reachability-status-subscription
As keeping Device Status family name relevant what we should do:
I tend to prefer option 2 for consistency but need guidance.
eric-murray
commented
2 weeks ago I support the proposal for CAMARA to define API Families, which consist of a set of related APIs, each of which can have a separate repository.
I'm not sure about the value of formally defining lead and child repositories. GitHub does not support hierarchical repositories, so the differences between such repositories will be somewhat "cosmetic" and create an additional maintenance overhead. My preference would be that the components of a family be defined in the wiki (where we currently have sub-projects), with links to each of the component repositories maintained there.
I take the point that there may be some artifacts common to a family but not so useful that they would be in Commonalities. I would leave it to the family to decide how to handle such artifacts. Generally, I think that (informational) supporting material should be hosted in the wiki rather than GitHub where possible. Anything normative should remain in GitHub, of course.
hdamker
commented
2 weeks ago @ToshiWakayama-KDDI @jlurien @shilpa-padgaonkar @bigludo7 @eric-murray
Thanks for your comments on the proposal. Based on your feedback I propose one major change of my above proposal (and have adapted the title accordingly): there will be no such thing like a "lead repository", but a Sub Project / API Family will be a set of 1 to n equal repositories to describe, develop, document and test the APIs (family members). That will mitigate the challenge raised by @jlurien and @bigludo7 and is in line with the proposal of @shilpa-padgaonkar.
A Sub Project in CAMARA to describe, develop, document and test APIs will have:
Each repository will have an own CODEOWNER and MAINTAINER.md file as proposed by @shilpa-padgaonkar.
On this base I will create to PR which will allow to discuss the details.
EDIT: the discussion of the proposal led to the decision to drop the "Lead_Repository" from the solution proposal, but define an API Family Sub Project simpler as a set of one or multiple API repositories. This change is not reflected here, but described within https://github.com/camaraproject/Governance/issues/142#issuecomment-2175408112
Problem description
The work within Release Management has shown that within one GitHub repository only one API or a few closely related APIs can be managed. The defined Release Process decouples the release numbering from the API version numbering, which allows in principle different API versions within one repository. But as a release is always on the complete repository including all APIs which are in the repository these APIs must always released at the same time, going through the same release cycle (of alpha/rc pre-releases and the public-release).
That wouldn't fit for APIs which are in different life-cycle staging, e.g. APIs which are in initial development phase with rapid releases and stable APIs which are following the meta-release cycle. As a consequence im many cases an API needs to have an own repository for to describe, develop, document and test of the API. Even if the API would fit into an existing "API Family" maintained by an existing CAMARA Sub Project.
Examples are "SimpleEdgeDiscovery", which belongs to "EdgeCloud", but has been split out into an own repository to allow proper release management, and "Tenure" which has been created in an own repository but is supposed to be maintained as part of the "KnowYourCustomer" family. Further APIs are in the API Backlog which have similar needs, or are currently together in a repository
Creating an own Sub Project for each API repository within CAMARA will not scale, as each Sub Project will need a group of (experienced) Maintainers and has administrative overhead (Wiki page, mailing list, regular meetings). A previous proposal to create a working group around a set of Sub Projects would not solve this administrative overhead but instead add another level of administrative overhead. Instead there is the need for an approach which limits the amount of Sub Projects in CAMARA but allows to develop and maintain a large number of APIs.
Possible evolution
The proposal is the following:
Each CAMARA Sub Project for the development of APIs will have a "Lead_Repository", which is the "home" of the API family and optional one or multiple
"child"repositories to describe, develop, document and test API family members (name to be defined, for the purpose here: "API_Repository")The Lead_Repository of a CAMARA API Family Sub Project will have all the components defined today in https://github.com/camaraproject/Governance/blob/main/ProjectStructureAndRoles.md for a lead repository (see also https://github.com/camaraproject/Template_Lead_Repository). It includes especially the MAINTAINERS.md file for the Sub Project, which defines the Maintainer team which is responsible for all APIs within the "family".
The Lead_Repository may contain one or few closely related APIs, which means that a new Sub Project which has (initially) only one API to develop will need only the lead repository (= which mean initially no change for most existing Sub Projects). But the Lead_Repository might have also no API definition itself, being only the home of common artefacts and documentation of the API family.
An API_Repository is linked to a Lead Repository and clearly defined (within the Readme) as a repository to describe, develop, document and test a specific API or closely related set of APIs in the context of a Sub Project API Family. The MAINTAINERS.md file points to the MAINTAINERS.md file in the Lead Repository (= the Maintainers of the Sub Project have the same responsibilities also for the API family member). The CODEOWNERS can be distinct from the Lead Repository (to distribute the workload within the Sub Project). Regarding mailing list, meeting schedule and meeting minutes there will be a link to the Lead Repository.
The approach of Lead_Repository and API_Repository allows the following "operations":
The sum of these operations allows to reorganise the API portfolio within CAMARA if needed, e.g. the consolidation of stable API definitions into API Family Sub Projects with larger number of APIs for long-term maintenance and evolution.
Alternative solution
The previous proposal described in https://github.com/camaraproject/Governance/issues/135 (one Sub Project per API, combining them via a working group) would not scale, see above in the problem description.
Additional context
Within the Governance documentation this approach can be defined with relative few additions, mainly the definition of an "API_Repository" (and the related Template repository).