Skip to content

docs: draft federated subproject governance model - #71

Draft
gbartolini wants to merge 4 commits into
mainfrom
dev/67
Draft

docs: draft federated subproject governance model#71
gbartolini wants to merge 4 commits into
mainfrom
dev/67

Conversation

@gbartolini

@gbartolini gbartolini commented Jul 15, 2026

Copy link
Copy Markdown
Contributor
  • Split governance into two documents: GOVERNANCE.md (collective bodies and their authority) and CONTRIBUTOR_LADDER.md (individual progression), so each can be amended at its own threshold (⅔ org-balanced for the former, simple majority for the latter).
  • Establish a federated model: a Steering Committee (5-7 seats, max 2 per organisation) sits above four Subproject Maintainer Committees (Core Projects, Supply Chain, Community, Docs & Ecosystem, Extensibility), each holding technical authority over its own repositories and selecting one representative to Steering.
  • Split voting into organization-level decisions (org-balanced, one vote per organisation: Steering Committee elections, GOVERNANCE.md changes, CONTRIBUTOR_LADDER.md changes, adding/removing subprojects) and subproject-level decisions (per-person, lazy consensus falling back to a plain vote).
  • Add a Community Representative election process: nominations open in a public Discussion in the governance repository, seats filled by ranked-choice voting (Condorcet or instant-runoff, e.g. via CIVS), and a vacancy rule that promotes the next-highest-ranked candidate from the original election before calling a special one.
  • Add organizational cap enforcement for the 2-per-organisation Steering seat limit, covering election results, subproject committee selections, and affiliation drift from an acquisition or a job change. The cap binds from the Steering Committee's very first appointment rather than only after initial terms expire, so the restructuring cannot itself reintroduce, even temporarily, the single-organisation majority it exists to end.
  • Add a documented path for proposing a new repository to join an existing subproject, and for archiving one that goes inactive, both decided by that subproject's own maintainer committee.
  • Collapse the Reviewer rung into Component Owner. Folder-scoped CODEOWNERS recognition (e.g. a docs/ or testing/ owner within a larger repository) becomes an operational tag a repository's own Component Owners can assign to any Contributor for review-routing, carrying no vote, no additional GitHub permission, and no CNPG Organization Member status. The ladder is now Community Participant, Contributor, Component Owner, Subproject Maintainer, with Steering Committee membership deliberately kept off the ladder as a representative role rather than a rung climbed to.
  • Redefine "component" as strictly a GitHub repository, dropping the earlier allowance for a functionally independent subdirectory to count as its own component.
  • Rename "Organization Member" to "CNPG Organization Member" throughout, to avoid confusion with the org-balanced-voting sense of "organization" (the employer an individual works for).
  • Restructure MAINTAINERS.md into per-subproject tables (Last Name, First Name, Handle, Organization, Component(s)) in place of bullet lists, and add an empty Steering Committee table, ready for Last Name, First Name, Handle, Organization, Seat, Email, Term Start, and Term End once seats are actually filled.
  • Add three previously undocumented maintainers found by cross-referencing CODEOWNERS data against the committee rosters: Itay Grudev to Supply Chain (owns charts), Armando Ruocco to Community, Docs & Ecosystem (owns webtest), and Niccolò Fei to Extensibility (owns plugin-barman-cloud).
  • Rescope CONTRIBUTORS.md to the Contributor tier specifically, removing nine names that had already progressed to Subproject Maintainer and are now recorded in MAINTAINERS.md instead, alongside a Component(s)-aware roster there.
  • Replace COMPONENT-OWNERS.md with the subprojects/ folder, one file per subproject listing real CODEOWNERS-derived repository ownership, plus a root CODEOWNERS file scoping each subprojects/*.md file to its own subproject's maintainer committee.
  • Update README.md's links to point at the new document set.
  • Open items not resolved in this change, flagged inline for follow-up: the Steering Committee's term-stagger schedule, inactivity thresholds for any tier, the Security Response Team and Infrastructure Team rosters, and whether Component Owner status should count toward CNCF's own foundation-level maintainer list and mailing list.

Closes #67
Refs #69

Assisted-by: Claude

@gbartolini
gbartolini marked this pull request as draft July 15, 2026 03:57
@gbartolini
gbartolini force-pushed the dev/67 branch 29 times, most recently from b9fb316 to 11cedd0 Compare July 20, 2026 04:35
@gbartolini
gbartolini force-pushed the dev/67 branch 6 times, most recently from 9c03ae8 to 5cdbab7 Compare July 21, 2026 00:23
Split governance into two documents: GOVERNANCE.md (collective bodies and their authority) and CONTRIBUTOR_LADDER.md (individual progression), so each can be amended at its own threshold (⅔ org-balanced for the former, simple majority for the latter).

Establish a federated model: a Steering Committee (5-7 seats, max 2 per organisation) sits above four Subproject Maintainer Committees (Core Projects, Supply Chain, Community, Docs & Ecosystem, Extensibility), each holding technical authority over its own repositories and selecting one representative to Steering.

Split voting into organization-level decisions (org-balanced, one vote per organisation: Steering Committee elections, GOVERNANCE.md changes, CONTRIBUTOR_LADDER.md changes, adding/removing subprojects) and subproject-level decisions (per-person, lazy consensus falling back to a plain vote).

Add a Community Representative election process: nominations open in a public Discussion in the governance repository, seats filled by ranked-choice voting (Condorcet or instant-runoff, e.g. via CIVS), and a vacancy rule that promotes the next-highest-ranked candidate from the original election before calling a special one.

Add organizational cap enforcement for the 2-per-organisation Steering seat limit, covering election results, subproject committee selections, and affiliation drift from an acquisition or a job change. The cap binds from the Steering Committee's very first appointment rather than only after initial terms expire, so the restructuring cannot itself reintroduce, even temporarily, the single-organisation majority it exists to end.

Add a documented path for proposing a new repository to join an existing subproject, and for archiving one that goes inactive, both decided by that subproject's own maintainer committee.

Collapse the Reviewer rung into Component Owner. Folder-scoped CODEOWNERS recognition (e.g. a docs/ or testing/ owner within a larger repository) becomes an operational tag a repository's own Component Owners can assign to any Contributor for review-routing, carrying no vote, no additional GitHub permission, and no CNPG Organization Member status. The ladder is now Community Participant, Contributor, Component Owner, Subproject Maintainer, with Steering Committee membership deliberately kept off the ladder as a representative role rather than a rung climbed to.

Redefine "component" as strictly a GitHub repository, dropping the earlier allowance for a functionally independent subdirectory to count as its own component.

Rename "Organization Member" to "CNPG Organization Member" throughout, to avoid confusion with the org-balanced-voting sense of "organization" (the employer an individual works for).

Restructure MAINTAINERS.md into per-subproject tables (Last Name, First Name, Handle, Organization, Component(s)) in place of bullet lists, and add an empty Steering Committee table, ready for Last Name, First Name, Handle, Organization, Seat, Email, Term Start, and Term End once seats are actually filled.

Add three previously undocumented maintainers found by cross-referencing CODEOWNERS data against the committee rosters: Itay Grudev to Supply Chain (owns charts), Armando Ruocco to Community, Docs & Ecosystem (owns webtest), and Niccolò Fei to Extensibility (owns plugin-barman-cloud).

Rescope CONTRIBUTORS.md to the Contributor tier specifically, removing nine names that had already progressed to Subproject Maintainer and are now recorded in MAINTAINERS.md instead, alongside a Component(s)-aware roster there.

Replace COMPONENT-OWNERS.md with the subprojects/ folder, one file per subproject listing real CODEOWNERS-derived repository ownership, plus a root CODEOWNERS file scoping each subprojects/*.md file to its own subproject's maintainer committee.

Update README.md's links to point at the new document set.

Open items not resolved in this change, flagged inline for follow-up: the Steering Committee's term-stagger schedule, inactivity thresholds for any tier, the Security Response Team and Infrastructure Team rosters, and whether Component Owner status should count toward CNCF's own foundation-level maintainer list and mailing list.

Closes #67
Refs #69

Assisted-by: Claude

Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
…ing org repos

Bring dev/67's federated governance model in line with the real GitHub
org state produced by a parallel cnpg-infra admin pass, and tidy up
naming along the way.

- Add `.github` and `cnpg-infra` to the set of repositories administered
  directly by the Steering Committee, alongside `governance` and
  `.project` (GOVERNANCE.md prose, embedded diagram, GitHub Project
  Administration section; subprojects/README.md; MAINTAINERS.md;
  project-organization.mermaid).
- Rewrite this repo's own CODEOWNERS: the `maintainers` team it
  referenced has been deleted org-wide, and the four subproject-committee
  teams it referenced never existed until now. All lines fall back to
  `governance-owners` (Steering-designate files and the default rule) or
  pair the four real-but-placeholder subproject-committee teams with
  `admins` (core-maintainers, supply-chain-maintainers,
  community-ecosystem-maintainers, extensibility-maintainers), since none
  of the four has been granted repo access yet.
- Update subprojects/README.md's GitHub Teams table and transitional
  note to match: the `maintainers` team is gone, `<repo>-owners` teams
  are real and cnpg-infra-managed today, and the four subproject-committee
  teams exist with placeholder membership only.
- State plainly, in GOVERNANCE.md's Infrastructure Administration section
  and subprojects/README.md's GitHub Teams section, that all GitHub teams
  and repository permissions are managed declaratively through the
  cnpg-infra repository rather than by hand.
- Rename the Core Projects subproject to Core (subprojects/core-projects.md
  -> subprojects/core.md), so its slug matches the existing
  `core-maintainers` team the same way the other three subprojects
  already do (<project>-maintainers).
- Add the two standalone project-organization.mermaid and
  contributor-ladder.mermaid diagrams to version control; they were
  edited earlier in this branch's history but never committed.

Refs #67

Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>

Assisted-by: Claude
Reconcile the federated governance draft against everything cnpg-infra's
real, current config has changed since the last sync (a9e06f8), and add
a new requirement raised by .project's LFID mandate.

Ownership/roster sync (real CODEOWNERS/repo-tiers.yaml state):
- Add `klio`, a real repo entirely missing from any subprojects/*.md
  listing, to extensibility.md's Interface & Plugins (CNPG-I) table and
  to MAINTAINERS.md's Extensibility committee (Francesco Canovai,
  Leonardo Cecchi, and two individuals new to this document, Gabriele
  Quaresima/@gabriele-wolfox and @GabriFedi97).
- Reflect Jaime Silvela's reduced ownership (cnpg-infra#7): drop him from
  cloudnative-pg's Documentation and Testing scopes (core.md), from
  cloudnative-pg.github.io (community-ecosystem.md), and from the
  Community, Docs & Ecosystem Maintainers table; he keeps `ciclops`.
- Add @GabriFedi97 to postgres-extensions-containers' owners
  (supply-chain.md, MAINTAINERS.md) and to Supply Chain Maintainers,
  matching componentowners-policy.yaml's own note that this was missing.
- Add Armando Ruocco to cnpg-playground, Francesco Canovai to
  pgbouncer-containers, and Leonardo Cecchi to postgres-trunk-containers
  — plain omissions against repo-tiers.yaml's real owners lists.
- Correct webtest's description to match its real GitHub description (a
  PostgreSQL stress tool, not website/doc test tooling) — repo-tiers.yaml
  flagged this as "confirmed wrong by Gabriele."

Structural fix:
- Reclassify `cnpg-template` from Supply Chain to the Steering-administered
  org-control group (alongside governance, .project, .github, cnpg-infra),
  per repo-tiers.yaml's own note that this was "a real discrepancy with
  governance worth reconciling there." Updates GOVERNANCE.md (prose,
  embedded diagram, GitHub Project Administration), the standalone
  project-organization.mermaid, subprojects/README.md, MAINTAINERS.md,
  and README.md — the last of which was still only listing `governance`
  and `.project` as the special case, predating even the .github/cnpg-infra
  addition from the previous sync.
- Add a note to GOVERNANCE.md's "Proposing a New Component" section that
  onboarding an accepted repo is now automated end-to-end by cnpg-infra's
  create-new-repo.sh.

New requirement: Linux Foundation ID (LFID)
- Add a "Determining Organizational Affiliation" subsection to
  GOVERNANCE.md, next to Organizational Cap Enforcement: every
  Maintainer, Component Owner, and Steering Committee member must hold
  an LFID with their correct, current employer, since that's what the
  2-per-organization cap and org-balanced voting actually rely on to
  determine "organization" — not self-reporting. MAINTAINERS.md's
  Organization column is sourced from this record, not entered
  independently.
- Add the same requirement to CONTRIBUTOR_LADDER.md's CNPG Organization
  Member section, and a pointer note to MAINTAINERS.md explaining that a
  blank Organization cell means a missing LFID record, not a real gap.
- Flagged as an open item: .project's maintainers.yaml doesn't carry
  LFID/organization data yet today, so this is the mechanism proposed,
  not something already in place.

Refs #67

Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>

Assisted-by: Claude
Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Rewrite GOVERNANCE.md: subprojects, maintainer committees, steering charter

1 participant