Governance update for Sandbox/Incubated/Graduated approach #161

hdamker · 2024-10-02T18:20:31Z

What type of PR is this?

enhancement
project management

What this PR does / why we need it:

To establish the approach described within #159 and discussed on this wiki page there are changes to Governance documents of CAMARA necessary.

This PR changes the ProjectCharter and the ProjectStructureAndRoles:

ProjectCharter
- defined "Sandbox Repositories" as potentially independent of Sub Projects or Working Groups
- clarified where necessary that Maintainers in the sense of the Charter are Maintainers of Sub Project and Working Groups (but not including the Maintainers of Sandbox Repositories)
ProjectStructureAndRoles
- introduced the maturity levels of Sandbox/Incubated/Graduated for API Repositories
- described the three types of API Repositories and their technical differentiation
- some small changes where seen necessary
- described the responsibilities of the APIBacklog Working Group
- replaced "Sub Projects" with "Sub Projects and Working Groups" where appropriate

To be done in separate PRs:

describe "Archived" repositories (after the process is described) in ProjectStructureAndRoles
Create the document "API-Onboarding-and-Lifecycle.md" which is referenced for the processes of onboarding a new Sandbox API Repository and their Incubation and Graduation. It will replace the current API-Onboarding.md document

Out of scope of this PR:

Further necessary changes within roles and responsibilities, especially regarding the "Participants.md" file and who are Project participants

Which issue(s) this PR fixes:

Fixes #

Special notes for reviewers:

Additional documentation

This section can be blank.

MarkusKuemmerle

The section

A Sandbox API Repository must have at least one Codeowner and one Maintainer (could be the same person). If branch protection rules are activated (on request of the Maintainers) within the repository it must have at least two Codeowners. Branch protection rules must be get activated at latest when the first public release is created.

is wrong, as sandbox API repos don't have maintainers

Please check the section about Release Management. Do Sandbox API repos also have to comply with the work in the commonalities Working Group?
Each Sub Project and each Sandbox API repository shall have a release management. ?

Please check the sections "Maintainers" and "Changes in maintainership". Maintainers are also relevant for Working Groups. The sentence
changing the MAINTAINERS.MD file of the respective Sub Project.
is wrong, Sub Projects don't have MAINTAINER files.

I'll create a separate issue for the clean up of "Project participants", "contributors" and the relation to PARTICIPANTS.MD.

ProjectStructureAndRoles.md

shilpa-padgaonkar · 2024-10-05T09:21:00Z

ProjectStructureAndRoles.md

-A Sub Project should have at least one Maintainer. Ideally a Sub Project is managed by two or more Maintainers, depending on the size and scope of the Sub Project. The Maintainers of a Sub Project are defined by the union of the Maintainers listed within the MAINTAINERS.md files of the API Repositories which are belonging to the Sub Project. It is recommended that there is an overlap between the Maintainers of the API Repositories of the Sub Project, but it is not mandated that all Maintainers of the Sub Project take responsibility for all APIs in the Sub Project.
+The purpose of an API Repository is the definition and documentation of one or multiple (very closely related) APIs which will be always released together.
+
+An API Repository should have at least one Maintainer. Ideally an API Repository is managed by two or more Maintainers, depending on the size and scope of the API. Here, the responsibilities must be clearly agreed upon between all of the Maintainers. This includes coordinating who is responsible for which issues and pull requests. The Contributors to an API Repository are recorded by the mechanisms of GitHub in the Sub Project’s repositories.


As concrete rules for Maintainers for incubated and sandbox repo are specified below, could we refer them here? Else, this can be look inconsistent. Or we can choose to remove this maintainer specific statement from here completely, as it's anyway covered below

ProjectStructureAndRoles.md

shilpa-padgaonkar · 2024-10-05T12:35:51Z

ProjectStructureAndRoles.md

@@ -48,7 +101,7 @@ In the Project the “Fork and pull model” is used. Changes and contributions

 2 Either the issue creator or one of the Sub Project Maintainers then shall assign the issue to one of the Contributors of the Sub Project.

-3 This Contributor shall create a fork (if necessary), shall create a new branch, and shall copy the branch link into the issue. For the naming of the branch a clear and concrete description shall be used.
+3 This Contributor shall create a fork (if not yet done before), shall create a new branch within the fork, and shall copy the branch link into the issue. For the naming of the branch a clear and concrete description shall be used.


Would copying the link in the issue be necessary? If we use the PR template and the #fixes tag, then this copying step is not needed. Probably not relevant for this PR but added this as this statement was part of the change.

You are right, by using the "fixes" logic of GitHub, the PR will get automatically copied into the issue. But it is also possible to link the branch already earlier (there is a field within a GitHub issue for that, which is e.g. filled if the branch will be created out of the issue). Making this optional could be the scope of a separate PR.

Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com>

ProjectCharter.md

Co-authored-by: Kevin Smith <Kevsy@users.noreply.github.com>

Update Release management with clarifications.

…hanges

hdamker · 2024-10-16T19:08:01Z

@MarkusKuemmerle Thanks for your review!

The section

A Sandbox API Repository must have at least one Codeowner and one Maintainer (could be the same person). If branch protection rules are activated (on request of the Maintainers) within the repository it must have at least two Codeowners. Branch protection rules must be get activated at latest when the first public release is created.

is wrong, as sandbox API repos don't have maintainers

I did changes to make maintainers for Sandbox API Repositories optional within 680d7cf

But we have to differentiate here between two cases:

A Sandbox API Repository which belongs to an existing Sub Project. Here the Sub Project has a defined set of Maintainers who will oversee also the Sandbox Repository. The existing Maintainers may nominate or approve already Maintainers for the Sandbox Repository which are then noted within the MAINTAINERS.
An independent Sandbox API Repository which is not (yet) part of a Sub Project. Here you are right, they can't have Maintainers in the sense of the ProjectCharter ("leaders of a Sub Project") as there is no Sub Project yet. But the Sandbox phase has also the purpose to attract contributors who are willing to take the role of Maintainers, e.g. after Incubation. Therefore I formulated the role of MAINTAINERS.md file within an independent Sandbox API Repository in this sense: as a list of participants committed to take the role after Incubation or adoption by a Sub Project.

Please check the section about Release Management. Do Sandbox API repos also have to comply with the work in the commonalities Working Group? Each Sub Project and each Sandbox API repository shall have a release management. ?

I tried to clarify this in 197a6a6 and 680d7cf mainly by the sentence within the definition of the Release Management working group: "All API and Working Group Repositories must comply with the work in the Release Management Working Group for releases and pre-releases."

Please check the sections "Maintainers" and "Changes in maintainership". Maintainers are also relevant for Working Groups. The sentence changing the MAINTAINERS.MD file of the respective Sub Project. is wrong, Sub Projects don't have MAINTAINER files.

Addressed within 680d7cf and c58a241 by replacing "Sub Projects" by "Sub Projects and Working Groups" wherever appropriate, correcting the sentence and adding the clarification that changes of maintainership of Working Groups are the responsibility of the TSC. I might still have missed some instances, please check and suggest needed changes.

I'll create a separate issue for the clean up of "Project participants", "contributors" and the relation to PARTICIPANTS.MD.

Thanks!

hdamker · 2024-10-16T19:16:59Z

Opening the PR for review, as the initial comments are (hopefully) addressed.
The "API-Onboarding-and-Lifecycle.md" document will be separate PR later.

jgarciahospital · 2024-10-17T06:15:10Z

ProjectStructureAndRoles.md

 **Sub Projects**

-The CAMARA Project is organized primarily into Sub Projects. Each Sub Project is composed of Project participants from multiple companies and organizations, with a common purpose of advancing the Sub Project with respect to a specific Service API topic, for example ‘quality on demand’ or ‘localization’. Our goal is to enable distributed decision making and code ownership. This will be done by providing focused forums for getting work done, making decisions, and onboarding new Contributors.
+Sub Projects are the primary structure of the CAMARA Project. Each Sub Project is composed of Project participants from multiple companies and organizations, with a common purpose of advancing the Sub Project with respect to a specific Service API topic, for example ‘quality on demand’ or ‘localization’. Our goal is to enable distributed decision making and code ownership. This will be done by providing focused forums for getting work done, making decisions, and onboarding new Contributors.


Should we include here the term family? As it has evolved from its creation, right now families are mostly parallelizing the subgroup concept, a group of APIs with a relation among them but separated in different repositories to ensure that there is not cross-dependancy in the specification. Location, qod... are good examples for API families.

I'm a bit skeptical to re introduce the family term. We had discussion on the past but is was difficult to define and we get ride of it. Sub project term is just go enough for me.

jgarciahospital · 2024-10-17T06:19:23Z

ProjectStructureAndRoles.md


-Working Groups are documented in a separate section of [wiki.camaraproject.org](https://wiki.camaraproject.org) and can have one or multiple GitHub repositories following the API Repository template (the rules for API Repositories apply). In the Readme.md file the repositories of Working Groups are marked with a "Working Group" badge.
+A Sandbox API Repository can belong to a CAMARA Sub Project or exist initially independent as an independent API Repository. 


Duplicated information with line 45

jgarciahospital · 2024-10-17T06:21:52Z

ProjectStructureAndRoles.md

-As mentioned before the contributions to the Sub Projects were documented in the respective GitHub repositories of the Sub Projects, and the contributions to Working Groups were documented in the GitHub repositories of the Working Groups. All contributions beyond that, esp. contributions to the Project itself or the TSC are documented in the GitHub repository “Governance”. Additional repositories can be created for project administration purposes. 
+* An independent Sandbox API Repository which is not part of an existing Sub Project will get a page in a separate section of the [CAMARA wiki](https://lf-camaraproject.atlassian.net/), a preliminary mailing list, a Slack channel, and (on request) a Zoom meeting to be able to communicate with the community and attract contributors. The MAINTAINERS.md file of an Independent Sub Project may already list contributors who are committed to the support the API Repository as Maintainers. But they are yet Maintainers of a Sub Project in the sense of the Project Charter.
+
+A Sandbox API Repository must have at least one Codeowner. If branch protection rules are activated within the repository it must have at least two Codeowners. Branch protection rules must get activated at latest when the first public release is created.


I'd delete the branch protection description here, since it's agreed that this not applies to sandbox repos.

jgarciahospital · 2024-10-17T06:25:38Z

ProjectStructureAndRoles.md

-For ease of use there are templates for the two types of Sub Project repositories (API and Provider Implementation Repositories), containing all necessary files which can be cloned and adapted. When cloning it has to be ensured that also the branch protection rules are active in the new repositories. For Working Group repositories the API Repository template should be used and adapted.
+An Incubated API Repository has the same structure as a Sandbox API Repository, with the following additional requirements: 
+* An Incubated API Repository must belong to a CAMARA Sub Project (either an existing one or a new Sub Project created as part of the Incubation process). 
+* The repository should have at least three Maintainers (out of the group of Maintainers of the Sub Project it belongs to). 


is it necessary to specify if the maintainers need to belong to different companies here? we discussed about this in the draft, both for maintainers support and market adoption rules.

Agree with @jgarciahospital that this point should be added.

bigludo7

Look globally good to me. Share small comment that Jorge about indication that maintainers for incubated projects should be from at least 2 distinct companies.

bigludo7 · 2024-10-17T07:03:55Z

ProjectStructureAndRoles.md

-For ease of use there are templates for the two types of Sub Project repositories (API and Provider Implementation Repositories), containing all necessary files which can be cloned and adapted. When cloning it has to be ensured that also the branch protection rules are active in the new repositories. For Working Group repositories the API Repository template should be used and adapted.
+An Incubated API Repository has the same structure as a Sandbox API Repository, with the following additional requirements: 
+* An Incubated API Repository must belong to a CAMARA Sub Project (either an existing one or a new Sub Project created as part of the Incubation process). 
+* The repository should have at least three Maintainers (out of the group of Maintainers of the Sub Project it belongs to). 


Agree with @jgarciahospital that this point should be added.

bigludo7 · 2024-10-17T07:05:18Z

ProjectStructureAndRoles.md

 **Sub Projects**

-The CAMARA Project is organized primarily into Sub Projects. Each Sub Project is composed of Project participants from multiple companies and organizations, with a common purpose of advancing the Sub Project with respect to a specific Service API topic, for example ‘quality on demand’ or ‘localization’. Our goal is to enable distributed decision making and code ownership. This will be done by providing focused forums for getting work done, making decisions, and onboarding new Contributors.
+Sub Projects are the primary structure of the CAMARA Project. Each Sub Project is composed of Project participants from multiple companies and organizations, with a common purpose of advancing the Sub Project with respect to a specific Service API topic, for example ‘quality on demand’ or ‘localization’. Our goal is to enable distributed decision making and code ownership. This will be done by providing focused forums for getting work done, making decisions, and onboarding new Contributors.


I'm a bit skeptical to re introduce the family term. We had discussion on the past but is was difficult to define and we get ride of it. Sub project term is just go enough for me.

hdamker added 2 commits October 2, 2024 16:27

Update ProjectCharter.md

9cfb817

Update ProjectStructureAndRoles.md

87ff272

MarkusKuemmerle requested changes Oct 4, 2024

View reviewed changes