diff --git a/toc/ROLES.md b/toc/ROLES.md index d0b61a2d..42802d64 100644 --- a/toc/ROLES.md +++ b/toc/ROLES.md @@ -61,7 +61,7 @@ establish sub-working groups. Working groups delegate change approval to Approve

Can join CF Slack workspace

Can take part in community discussions

- GitHub Organization + Per GitHub Organization @@ -75,7 +75,7 @@ establish sub-working groups. Working groups delegate change approval to Approve

Can get PRs accepted

- GitHub Organization + Per GitHub Organization @@ -88,10 +88,9 @@ establish sub-working groups. Working groups delegate change approval to Approve

Has made multiple contributions to the project

-

Member of the GitHub cloudfoundry (and possibly the cloudfoundry-incubator) orgs

-

Member of the Cloud Foundry Slack workspace

+

Member of a CFF GitHub Organization

- GitHub Organization + Per GitHub Organization @@ -226,11 +225,11 @@ this is not a requirement. - Contributing to working group or community discussions. -- Subscribed to - [cf-dev@lists.cloudfoundry.org](https://lists.cloudfoundry.org/g/cf-dev). - - Actively contributing to 1 or more areas. +- For Cloud Foundry Contributors: Subscribed to + [cf-dev@lists.cloudfoundry.org](https://lists.cloudfoundry.org/g/cf-dev). + ### Responsibilities and privileges - Responsive to issues and PRs assigned to them. diff --git a/toc/rfc/rfc-0002-github-members.md b/toc/rfc/rfc-0002-github-members.md index ab6b154c..b9c34fec 100644 --- a/toc/rfc/rfc-0002-github-members.md +++ b/toc/rfc/rfc-0002-github-members.md @@ -1,6 +1,6 @@ # Meta [meta]: #meta -- Name: Who is able to add and remove members of the Cloudfoundry GitHub org +- Name: Who is able to add and remove members of CFF Github Orgs - Start Date: 2022-01-26 - Author(s): @LeePorte - Status: Accepted @@ -9,25 +9,47 @@ ## Summary -Working group leads and approvers are the primary roles responsible for granting GitHub users membership in the `cloudfoundry` GitHub org, as they have the most context on which users within the CF community meet the criteria to be regular contributors. +Working group leads and approvers are the primary roles responsible for +granting GitHub users membership to the CFF Github Orgs, as they have +the most context on which users within the community meet the criteria to be +regular contributors. -The TOC is the body responsible for removing an existing member from the `cloudfoundry` GitHub org and coordinating with working groups to ensure that the removal does not have unexpected consequences. +The TOC is the body responsible for removing an existing member from the CFF +Github Orgs and coordinating with working groups to ensure that the removal +does not have unexpected consequences. ## Problem -Under the previous dojo-based participation model, a central team of VMware admins was primarily responsible for managing the members of the `cloudfoundry` GitHub org. In the current system of CF community roles and responsibilities, however, that delegation to the administrative team of a single member company no longer makes sense. +Under the previous dojo-based participation model, a central team of VMware +admins was primarily responsible for managing the members of the CFF Github +Orgs . In the current system of CF community roles and responsibilities, +however, that delegation to the administrative team of a single member company +no longer makes sense. ## Proposal -As defined in the [roles](https://github.com/cloudfoundry/community/blob/main/toc/ROLES.md), each Contributor -should be a member of the `cloudfoundry` GitHub org. -The leads and approvers within a Working Group are best positioned to decide whether an individual has met the minimum contribution criteria to become an official contributor. - -A Working Group approver or lead should raise a [PR on the community repository](https://github.com/cloudfoundry/community/pulls) to propose adding a new member to the `cloudfoundry` GitHub org. -This PR should add the member directly to the file in the [organizational structure directory](https://github.com/cloudfoundry/community/tree/main/org) that contains the list of contributors. Automation will periodically synchronize the GitHub org membership with the files in this directory. -Only Working Group leads and the TOC will actually have permission to merge these PRs under the planned access control on the community repository. - -As removing a member from the `cloudfoundry` GitHub org may have unintended consequences across the organization, the TOC is the body required to approve those removals. -Proposals to remove a member should also be submitted via PR, and the submitter should tag the PR with `toc` and should mention `@cloudfoundry/toc` to make the TOC aware of the request. -The TOC will then consult any working groups that may be affected by the removal of this member and use its usual decision process to approve or reject the removal. +As defined in the +[roles](https://github.com/cloudfoundry/community/blob/main/toc/ROLES.md), each +Contributor should be a member of the appropriate CFF Github Org(s). The leads +and approvers within a Working Group are best positioned to decide whether an +individual has met the minimum contribution criteria to become an official +contributor. + +A Working Group approver or lead should raise a [PR on the community +repository](https://github.com/cloudfoundry/community/pulls) to propose adding +a new member to a CFF Github Org. This PR should add the member directly to the +file in the [organizational structure +directory](https://github.com/cloudfoundry/community/tree/main/org) that +contains the list of contributors. Automation will periodically synchronize the +GitHub org membership with the files in this directory. Only Working Group +leads and the TOC will actually have permission to merge these PRs under the +planned access control on the community repository. + +As removing a member from a CFF GitHub Org may have unintended consequences +across the organization, the TOC is the body required to approve those +removals. Proposals to remove a member should also be submitted via PR, and the +submitter should tag the PR with `toc` and should mention `@cloudfoundry/toc` +to make the TOC aware of the request. The TOC will then consult any working +groups that may be affected by the removal of this member and use its usual +decision process to approve or reject the removal. diff --git a/toc/rfc/rfc-0007-repository-ownership.md b/toc/rfc/rfc-0007-repository-ownership.md index e4afaf87..f3bb2a1a 100644 --- a/toc/rfc/rfc-0007-repository-ownership.md +++ b/toc/rfc/rfc-0007-repository-ownership.md @@ -9,61 +9,132 @@ ## Summary -Adding a repository to the ownership scope of a Working Group, removing a repository from its scope, or transferring a repository between Working Groups within the `cloudfoundry` GitHub organization requires approval separately from each affected Working Group and from the Technical Oversight Committee (TOC). +Adding a repository to the ownership scope of a Working Group, removing a +repository from its scope, or transferring a repository between Working Groups +requires approval separately from each affected Working Group and from the +Technical Oversight Committee (TOC). ## Problem -As the CF community completes its rollout of the new TOC and Working Group governance structure, the large number of unaddressed PRs about repository ownership across Working Groups has illustrated that the community needs a clearer and more consistent process to handle such ownership changes. In particular, there are currently a significant number of repositories in the [`cloudfoundry`](https://github.com/cloudfoundry) and [`cloudfoundry-incubator`](https://github.com/cloudfoundry-incubator) GitHub organizations that are not yet officially assigned to a Working Group, and the community must decide which ones will be managed by which Working Groups and which ones will be archived. +As the CF community completes its rollout of the new TOC and Working Group +governance structure, the large number of unaddressed PRs about repository +ownership across Working Groups has illustrated that the community needs a +clearer and more consistent process to handle such ownership changes. In +particular, there are currently a significant number of repositories in the +[`cloudfoundry`](https://github.com/cloudfoundry) and +[`cloudfoundry-incubator`](https://github.com/cloudfoundry-incubator) GitHub +organizations that are not yet officially assigned to a Working Group, and the +community must decide which ones will be managed by which Working Groups and +which ones will be archived. -Even after the CF community resolves the ownership of the existing repositories in these two GitHub organizations, it still needs a clear process to create new repositories under a Working Group, to move repositories between Working Groups, and to remove a repository from a Working Group. +Even after the CF community resolves the ownership of the existing repositories +in these two GitHub organizations, it still needs a clear process to create new +repositories under a Working Group, to move repositories between Working +Groups, and to remove a repository from a Working Group. ## Proposal ### Ownership model -We can represent the ownership structure of the repositories in the `cloudfoundry` GitHub organization as a partition of the set of repositories. Each Working Group has a subset of repositories that it owns, and there are separate subsets under ownership of the TOC and of the CF Foundation staff, respectively. Finally, there are two separate subsets of unmanaged repositories: ones that are archived and ones that are active. Since this collection of subsets is a partition, the subsets MUST be mutually exclusive and comprehensively exhaustive: each repository in the organization is in exactly one of these subsets. - -The subset of repositories that each Working Group owns MUST be identical to the set of repositories listed in its charter description. This set of repositories MAY further be partitioned into technical areas within the Working Group, at the discretion of the Working Group. - -The subsets of repositories that the TOC and the CF Foundation staff own SHOULD be as small as possible and should be scoped to those that enable the effective operation of the CF community. These repostiories SHOULD NOT be concerned with development of tools and systems that are broadly valuable to the end-user community, as the Working Groups collectively SHOULD own those kinds of repositories instead. These two sets of repositories MUST be listed in the charter document for the TOC in this repository. - -The subset of unmanaged active repositories SHOULD be empty under steady-state operation. The community MUST collectively act to resolve the status of an unmanaged active repository within a reasonable period of time, either by archiving it or by placing it under the ownership of a Working Group, of the TOC, or of the CFF staff, as is appropriate. - -The ownership structure of the repositories in the `cloudfoundry-incubator` GitHub organization can be described the same way as a partition of the set of repositories amongst the Working Groups. Since incubation is no longer a relevant concept in CF Foundation governance, the community SHOULD act to move all of the active repositories in this organization to the main `cloudfoundry` GitHub organization in a reasonable period of time, while coordinating with the Working Groups to minimize negative effects on development and release practices. The community MUST NOT create new repositories in the `cloudfoundry-incubator` GitHub organization and MUST NOT move any existing repositories into it. +We can represent the ownership structure of the repositories in CFF Managed +Github Orgs as a partition of the set of repositories. Each Working Group has a +subset of repositories that it owns, and there are separate subsets under +ownership of the TOC and of the CF Foundation staff, respectively. Finally, +there are two separate subsets of unmanaged repositories: ones that are +archived and ones that are active. Since this collection of subsets is a +partition, the subsets MUST be mutually exclusive and comprehensively +exhaustive: each repository in a CFF Managed Github Org is in exactly one of +these subsets. + +The subset of repositories that each Working Group owns MUST be identical to +the set of repositories listed in its charter description. This set of +repositories MAY further be partitioned into technical areas within the Working +Group, at the discretion of the Working Group. + +The subsets of repositories that the TOC and the CF Foundation staff own SHOULD +be as small as possible and should be scoped to those that enable the effective +operation of the CF community. These repostiories SHOULD NOT be concerned with +development of tools and systems that are broadly valuable to the end-user +community, as the Working Groups collectively SHOULD own those kinds of +repositories instead. These two sets of repositories MUST be listed in the +charter document for the TOC in this repository. + +The subset of unmanaged active repositories SHOULD be empty under steady-state +operation. The community MUST collectively act to resolve the status of an +unmanaged active repository within a reasonable period of time, either by +archiving it or by placing it under the ownership of a Working Group, of the +TOC, or of the CFF staff, as is appropriate. + +The ownership structure of the repositories in the `cloudfoundry-incubator` +GitHub organization can be described the same way as a partition of the set of +repositories amongst the Working Groups. Since incubation is no longer a +relevant concept in CF Foundation governance, the community SHOULD act to move +all of the active repositories in this organization to the main `cloudfoundry` +GitHub organization in a reasonable period of time, while coordinating with the +Working Groups to minimize negative effects on development and release +practices. The community MUST NOT create new repositories in the +`cloudfoundry-incubator` GitHub organization and MUST NOT move any existing +repositories into it. ### Ownership changes -A change to repository ownership is a change to the partition of the set of repositories in the `cloudfoundry` organization. For a single repository, the possible changes are the addition of a new repository to the one of the subsets in the partition, the transfer of an existing repository from one subset to another, or the removal of a repository from a subset. +A change to repository ownership is a change to the partition of the set of +repositories in CFF Managed Github Organization. For a single repository, the +possible changes are the addition of a new repository to the one of the subsets +in the partition, the transfer of an existing repository from one subset to +another, or the removal of a repository from a subset. -Addition of a repository to the partition corresponds either to creating a new repository or transferring an existing repository from another GitHub organization. +Addition of a repository to the partition corresponds either to creating a new +repository, transferring an existing repository from another GitHub +organization, or adding an additional Github Organization to the list of CFF +Managed Github Organizations. -Removal of a repository corresponds either to transferring it to another GitHub organization or to deleting the repository entirely, neither of which should be undertaken lightly. The CF community SHOULD ensure that either of these cases receives thorough consideration and scrutiny before proceeding. +Removal of a repository corresponds either to transferring it to a non-CFF +Managed GitHub Organization or to deleting the repository entirely, neither of +which should be undertaken lightly. The CF community SHOULD ensure that either +of these cases receives thorough consideration and scrutiny before proceeding. -Proposed changes to repository ownership SHOULD be submitted for consideration as a pull request on the [Cloud Foundry community repository](https://github.com/cloudfoundry/community) that modifies the charter documents of the appropriate Working Groups. As per [RFC 0003](rfc-0003-pr-only-workflow.md), a pull request is preferable in order to provide visibility in the CF community, to encourage asynchronous discussion across time zones, and to reduce fragmentation of discussion. +Proposed changes to repository ownership SHOULD be submitted for consideration +as a pull request on the [Cloud Foundry community +repository](https://github.com/cloudfoundry/community) that modifies the +charter documents of the appropriate Working Groups. As per [RFC +0003](rfc-0003-pr-only-workflow.md), a pull request is preferable in order to +provide visibility in the CF community, to encourage asynchronous discussion +across time zones, and to reduce fragmentation of discussion. ### Ownership change approvals -The TOC MUST approve any change to repository ownership, just as it originally approved the initial set of repositories for each Working Group. Approval consists of a quorum decision by the TOC. +The TOC MUST approve any change to repository ownership, just as it originally +approved the initial set of repositories for each Working Group. Approval +consists of a quorum decision by the TOC. -Additionally, if a change affects the subset of repositories that a Working Group owns, that Working Group MUST approve the change as well. Approval consists of a quorum decision by the leads of the Working Group. +Additionally, if a change affects the subset of repositories that a Working +Group owns, that Working Group MUST approve the change as well. Approval +consists of a quorum decision by the leads of the Working Group. -The TOC MUST also approve of any proposal to create a new repository within the `cloudfoundry` GitHub organization or to rename an existing repository. +The TOC MUST also approve of any proposal to create a new repository within a +CFF Managed Github Organization or to rename an existing repository. -We illustrate several different cases of repository ownership changes and the approvals required for them to proceed: +We illustrate several different cases of repository ownership changes and the +approvals required for them to proceed: #### Case 1: A Working Group wants to create a new repository under their ownership. Approval requirements -* The Working Group MUST approve the addition of the proposed repository to the set of repositories that it owns. +* The Working Group MUST approve the addition of the proposed repository to the + set of repositories that it owns. * The TOC MUST approve the creation of the proposed repository. -* The TOC MUST approve the addition of the proposed repository to the Working Group's subset. +* The TOC MUST approve the addition of the proposed repository to the Working + Group's subset. Steps -1. Someone opens a PR that: adds the repo to the [cloudfoundry.yml](../../org/cloudfoundry.yml) and adds the repo to the desired Working Group's yaml. +1. Someone opens a PR that: adds the repo to the + [cloudfoundry.yml](../../org/cloudfoundry.yml) and adds the repo to the + desired Working Group's yaml. 2. The Working Group and TOC both approve the PR. 3. The TOC merges the PR. @@ -82,34 +153,46 @@ Steps #### Case 3: Working Group A wants to claim ownership of a repository currently owned by Working Group B. Approval requirements -* Both Working Group A and Working Group B MUST approve the change to the sets of repositories they own. -* The TOC MUST also approve the transfer of the repository from Working Group B to Working Group A. +* Both Working Group A and Working Group B MUST approve the change to the sets + of repositories they own. +* The TOC MUST also approve the transfer of the repository from Working Group B + to Working Group A. Steps -1. Someone opens a PR that moves a repo from Working Group A's yaml to Working Group B's yaml. +1. Someone opens a PR that moves a repo from Working Group A's yaml to Working + Group B's yaml. 2. Working Group A, Working Group B, and TOC approve the PR. 3. The TOC merges the PR. #### Case 4: A Working Group wants to archive a repository that it currently owns. Approval requirements -* The Working Group MUST approve the removal of the repository from the set of repositories that it owns. -* The TOC MUST approve the removal of the repository from the Working Group and the archival. +* The Working Group MUST approve the removal of the repository from the set of + repositories that it owns. +* The TOC MUST approve the removal of the repository from the Working Group and + the archival. Steps -1. Someone opens a PR that: marks the repo as archived in the [cloudfoundry.yml](../../org/cloudfoundry.yml) and that removes the repo from the Working Group's yaml. +1. Someone opens a PR that: marks the repo as archived in the + [cloudfoundry.yml](../../org/cloudfoundry.yml) and that removes the repo from + the Working Group's yaml. 2. The Working Group and TOC both approve the PR. 3. The TOC merges the PR. #### Case 5: A Working Group wants to delete a repository that it currently owns. -⚠️ Deleting a repository will usually be rejected by the TOC. Please consider archiving instead. +⚠️ Deleting a repository will usually be rejected by the TOC. Please consider +archiving instead. Approval requirements -* The Working Group MUST approve the removal of the repository from the set of repositories that it owns. -* The TOC MUST approve the removal of the repository from the Working Group and the deletion. +* The Working Group MUST approve the removal of the repository from the set of + repositories that it owns. +* The TOC MUST approve the removal of the repository from the Working Group and + the deletion. Steps -1. Someone opens a PR that removes the [cloudfoundry.yml](../../org/cloudfoundry.yml) and removes the repo from the Working Group's yaml. +1. Someone opens a PR that removes the + [cloudfoundry.yml](../../org/cloudfoundry.yml) and removes the repo from the + Working Group's yaml. 2. The Working Group and TOC both approve the PR. 3. The TOC merges the PR. 4. A github admin deletes the repo. @@ -117,25 +200,34 @@ Steps #### Case 6: A Working Group wants to cease maintaining a repository that it currently owns. Approval requirements -* The Working Group MUST approve the removal of the repository from the set of repositories that it owns. +* The Working Group MUST approve the removal of the repository from the set of + repositories that it owns. * The TOC MUST approve the removal of the repository from the Working Group. -* In addition, the TOC MUST decide whether to archive the repository or to arrange for another Working Group to own it instead (possibly a newly formed one, if appropriate and if supported by community contributors). -* Note: In this case, it is unlikely that either the TOC or the CFF staff should own this repository, as it was already owned by some Working Group in the CF community. +* In addition, the TOC MUST decide whether to archive the repository or to + arrange for another Working Group to own it instead (possibly a newly formed + one, if appropriate and if supported by community contributors). +* Note: In this case, it is unlikely that either the TOC or the CFF staff + should own this repository, as it was already owned by some Working Group in + the CF community. Steps 1. Someone opens a PR that removes the repo from the Working Group's yaml. -2. The TOC reviews and decides what action to take with the repo. Other PRs might be required for this step. +2. The TOC reviews and decides what action to take with the repo. Other PRs + might be required for this step. 3. The Working Group and TOC both approve the PR. 5. The TOC merges the PR. #### Case 7: A Working Group wants to rename a repository that it currently owns. Approval requirements -* The Working Group A and the TOC MUST both approve of the new name for the repository. +* The Working Group A and the TOC MUST both approve of the new name for the + repository. Steps -1. Someone opens a PR that: renames the repo in the [cloudfoundry.yml](../../org/cloudfoundry.yml) and renames the repo in the Working Group's yaml. +1. Someone opens a PR that: renames the repo in the + [cloudfoundry.yml](../../org/cloudfoundry.yml) and renames the repo in the + Working Group's yaml. 2. The Working Group and TOC both approve the PR. 3. The TOC stops the Github automation. 4. The TOC merges the PR. diff --git a/toc/rfc/rfc-0014-github-teams-and-access.md b/toc/rfc/rfc-0014-github-teams-and-access.md index 877536a8..e33d5cdf 100644 --- a/toc/rfc/rfc-0014-github-teams-and-access.md +++ b/toc/rfc/rfc-0014-github-teams-and-access.md @@ -9,7 +9,8 @@ ## Summary -All working groups SHOULD create GitHub teams using the standardized name format. +All working groups SHOULD create GitHub teams using the standardized name +format. Supersedes [rfc-0005-github-teams-and-access](https://github.com/cloudfoundry/community/blob/main/toc/rfc/archived/rfc-0005-github-teams-and-access.md) @@ -24,8 +25,9 @@ We need ways within the community to: ## Proposal -Every working group SHOULD use GitHub teams within the `cloudfoundry` org to reflect the following groups. The GitHub teams SHOULD be provisioned -automatically from the yaml blocks in the working group charters. +Every working group SHOULD use GitHub teams within the necessary CFF Managed +Github Org to reflect the following groups. The GitHub teams SHOULD be +provisioned automatically from the yaml blocks in the working group charters. | Name of Team | Team Membership | Permissions | |---|---|---| @@ -39,5 +41,8 @@ automatically from the yaml blocks in the working group charters. | wg-[WORKING-GROUP-NAME]-[AREA-NAME]-bots | Bot accounts for an area within a WG | Write access for all repos in the area | Where: -* `WORKING-GROUP-NAME` is the name of the Working Group, converted to kebab case, -* `AREA-NAME` is the name of the area, also converted to kebab case, or a suitable short name that identifies it clearly and uniquely within the Working Group. +* `WORKING-GROUP-NAME` is the name of the Working Group, converted to kebab + case, +* `AREA-NAME` is the name of the area, also converted to kebab case, or a + suitable short name that identifies it clearly and uniquely within the + Working Group. diff --git a/toc/rfc/rfc-draft-multiple-github-orgs.md b/toc/rfc/rfc-draft-multiple-github-orgs.md new file mode 100644 index 00000000..ea080831 --- /dev/null +++ b/toc/rfc/rfc-draft-multiple-github-orgs.md @@ -0,0 +1,70 @@ +# Meta +[meta]: #meta +- Name: Managing Multiple Github Orgs +- Start Date: 2025-01-21 +- Author(s): @ameowlia, @rkoster +- Status: Draft +- RFC Pull Request: (fill in with PR link after you submit it) + +## Summary + +CFF documentation and automation MUST be updated to be able to handle multiple +Github Orgs. + +## Problem + +Currently the documentation in the CFF community repo is written as if there is +only one Github Organization: cloudfoundry. However, there are currently two +Github Organizations that the CFF TOC oversees: cloudfoundry and paketo. In the +near future, we plan to add a third Github Organization: concourse. + +We MUST our documentation to reflect how we want to handle multiple Github organizations. + +## Proposal + +### New Definitions + +* *CFF Github Orgs* - This includes ALL Github Organizations that the CFF TOC + oversees. This currently includes: cloudfoundry and paketo. When we merge + [the RFC to add + concourse](https://github.com/cloudfoundry/community/pull/1047), then + concourse will also be included in this list. + +* *CFF Managed Github Orgs* - This includes all Github organizations that are + managed via the CFF TOC automation. This currently only includes + cloudfoundry. + +### Rename `org` dir to `orgs` +Currently the directory +[org](https://github.com/cloudfoundry/community/tree/main/org) contains yaml +definitions for the repos and contributors to the cloudfoundry Github org. It +also contains the CFF TOC org management automation scripts. + +This SHOULD be the place where yaml definitions for all CFF Managed Github orgs +are stored. To reflect this, the name of the directory SHOULD be renamed to `orgs`. + +### Rename `cloudfoundry.yml` to `orgs.yml` + +Currently +[cloudfoundry.yml](https://github.com/cloudfoundry/community/blob/main/org/cloudfoundry.yml) +contains yaml defining all of the repos in the cloudfoundry Github org. It +already has a top level [`orgs` +key](https://github.com/cloudfoundry/community/blob/8c7298337a8515d7dfae058b3bd1f88ad0eeaf95/org/cloudfoundry.yml#L2). + +All of the repos for all of CFF Managed Github Orgs SHOULD be in one place, and +the file `cloudfoundry.yml` SHOULD be the place for that. To reflect that this +file will contain information about multiple CFF Managed Github Orgs it SHOULD +be renamed `orgs.yml`. + +### Update other docs to match +All other files that contain references to the cloudfoundry Github org as if it +is the only Github org MUST be updated. + +This includes, but is not limited to the following files: +* https://github.com/cloudfoundry/community/blob/main/toc/rfc/rfc-0002-github-members.md +* https://github.com/cloudfoundry/community/blob/main/toc/rfc/rfc-0007-repository-ownership.md +* https://github.com/cloudfoundry/community/blob/main/toc/rfc/rfc-0014-github-teams-and-access.md +* https://github.com/cloudfoundry/community/blob/main/toc/ROLES.md + +### Update automation +The Github automation maintained by the TOC MUST be updated to work for multiple orgs.