Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit ad2c0c7

Browse files
mheonmheon
committedMar 14, 2025·
Add initial draft of Podman project Governance
This is the initial version of the governance model we're looking to implement. It is still very early, and comments and suggestions are very welcome! Signed-off-by: Matt Heon <[email protected]>
1 parent 73795f4 commit ad2c0c7

File tree

4 files changed

+337
-2
lines changed

4 files changed

+337
-2
lines changed
 

‎GOVERNANCE.md

+193
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Contributor Ladder Template
2+
3+
* [Contributor Ladder](#contributor-ladder-template)
4+
* [Contributor](#contributor)
5+
* [Reviewer](#reviewer)
6+
* [Maintainer](#maintainer)
7+
* [Core Maintainer](#coremaintainer)
8+
* [Community Manager](#communitymanager)
9+
* [Inactivity](#inactivity)
10+
* [Involuntary Removal](#involuntary-removal-or-demotion)
11+
* [Stepping Down/Emeritus Process](#stepping-downemeritus-process)
12+
* [Updates to this Document](#updates-to-this-document)
13+
* [Contact](#contact)
14+
15+
16+
## Contributor Ladder
17+
18+
Hello! We are excited that you want to learn more about our project contributor ladder! This contributor ladder outlines the different contributor roles within the project, along with the responsibilities and privileges that come with them. Community members generally start at the first levels of the "ladder" and advance as their involvement in the project grows. Our project members are happy to help you advance along the contributor ladder. At all levels, contributors are required to follow the CNCF Code of Conduct (COC).
19+
20+
Each of the project member roles below is organized into lists of three types of things.
21+
22+
* "Responsibilities" – functions of a member
23+
* "Requirements" – qualifications of a member
24+
* "Privileges" – entitlements of member
25+
26+
27+
### Contributor
28+
Description: A Contributor contributes directly to the project and adds value to it. Contributions need not be code. People at the Contributor level may be new contributors, or they may only contribute occasionally.
29+
30+
* Responsibilities include:
31+
* Follow the CNCF CoC
32+
* Follow the project contributing guide
33+
* Requirements (one or several of the below):
34+
* Report and sometimes resolve issues against any of the project’s repositories
35+
* Occasionally submit PRs against any of the project’s repositories
36+
* Contribute to project documentation, including the manpages, tutorials, and Podman.io
37+
* Attend community meetings when reasonable
38+
* Answer questions from other community members on the mailing list, Slack, Matrix, and other communication channels
39+
* Assist in triaging issues
40+
* Assist in reviewing pull requests, including testing patches when applicable
41+
* Test release candidates and provide feedback
42+
* Promote the project in public
43+
* Help run the project infrastructure
44+
* Privileges:
45+
* Invitations to contributor events
46+
* Eligible to become a Reviewer
47+
48+
### Reviewer
49+
Description: A Reviewer has responsibility for the triage of issues and review of pull requests on the Podman project or a subproject, consisting of one or more of the Git repositories that form the project. They are collectively responsible, with other Reviewers, for reviewing changes to the repository or repositories and indicating whether those changes are ready to merge. They have a track record of contribution and review in the project.
50+
51+
Reviewers have all the rights and responsibilities of a Contributor, plus:
52+
53+
* Responsibilities include:
54+
* Regular contribution of pull requests to the Podman project or its subprojects
55+
* Triage of Github issues on the Podman project or its subprojects
56+
* Regularly fixing Github issues on the Podman project or its subprojects
57+
* Following the [reviewing guide](./REVIEWING.md)
58+
* A sustained high level of pull request reviews on the Podman project or one of its subprojects
59+
* Assisting new Contributors with the process of contributing
60+
* Helping other contributors become reviewers
61+
* Requirements:
62+
* Has a proven record of good-faith contributions to the project as a Contributor for a period of at least 6 months. The time requirement may be overridden by a supermajority vote of Maintainers.
63+
* Has participated in pull request review and/or issue triage on the project for at least 6 months. The time requirement may be overridden by a supermajority vote of Maintainers.
64+
* Is supportive of new and occasional contributors and helps get useful PRs in shape to merge
65+
* Additional privileges:
66+
* Has rights to approve pull requests in the Podman project or a subproject, marking them as ready for a Maintainer to review and merge
67+
* Can recommend and review other contributors to become Reviewers
68+
69+
All Reviewers are listed in the OWNERS file of the repository or repositories they have review authority over.
70+
71+
72+
#### The process of becoming a Reviewer is:
73+
1. The contributor must be sponsored by a Maintainer. That sponsor will open a PR against the appropriate repository, which adds the contributor to the MAINTAINERS.md file as a reviewer.
74+
2. The contributor will add a comment to the pull request indicating their willingness to assume the responsibilities of a Reviewer.
75+
3. At least two Maintainers of the repository must concur to merge the PR.
76+
77+
### Maintainer
78+
Description: Maintainers are very established contributors with deep technical knowledge of the Podman project and/or one of its subprojects. Maintainers are granted the authority to merge pull requests, and are expected to participate in making decisions about the strategy and priorities of the project. Maintainers are responsible for code review and merging in a single repository or subproject. It is possible to become Maintainer of additional repositories or subprojects, but each additional repository or project will require a separate application and vote. They are able to participate in all maintainer activities, including Core Maintainer meetings, but do not have a vote at Core Maintainer meetings.
79+
80+
In repositories using an OWNERS file, Maintainers are listed as Approvers in that file.
81+
82+
A Maintainer must meet the responsibilities and requirements of a Reviewer, plus:
83+
* Responsibilities include:
84+
* Sustained high level of reviews of pull requests to the project or subproject, with a goal of one or more a week when averaged across the year.
85+
* Merging pull requests which pass review
86+
* Mentoring new Reviewers
87+
* Participating in CNCF maintainer activities for the projects they are maintainers of
88+
* Assisting Core Maintainers in determining strategy and policy for the project
89+
* Participating in, and leading, community meetings
90+
* Requirements
91+
* Experience as a Reviewer for at least 6 months, or status as an Emeritus Maintainer. The time requirement may be overridden by a supermajority vote of Maintainers.
92+
* Demonstrates a broad knowledge of the project or one or more of its subprojects
93+
* Is able to exercise judgment for the good of the project, independent of their employer, friends, or team
94+
* Mentors contributors, reviewers, and new maintainers
95+
* Collaborates with other Maintainers to work on complex contributions
96+
* Can commit to maintaining a high level of contribution to the project or one of its subprojects
97+
* Additional privileges:
98+
* Represent the project in public as a senior project member
99+
* Communicate with the CNCF on behalf of the project
100+
* Have a voice, but not a vote, in Core Maintainer decision-making meetings
101+
102+
#### Process of becoming a maintainer:
103+
1. A current reviewer must be sponsored by a Maintainer of the repository in question. The Maintainer will open a PR against the repository and add the nominee as an Approver in the MAINTAINERS.md file. The need for a sponsor is removed for Emeritus Maintainers, who may open this pull request themselves.
104+
2. The nominee will add a comment to the PR confirming that they agree to all requirements and responsibilities of becoming a Maintainer.
105+
3. A majority of the current Maintainers of the repository or subproject must then approve the PR. The need for a majority is removed for Emeritus Maintainers, who require only 2 current maintainers to approve their return.
106+
107+
### Core Maintainer
108+
Description: As the Podman project is composed of a number of subprojects, most maintainers will not have full knowledge of the full project and all its technical aspects. Those that do are eligible to become Core Maintainers, responsible for decisions affecting the entire project. Core Maintainers may act as a maintainer in all repositories and subprojects of the Podman Project.
109+
110+
* Responsibilities include:
111+
* All responsibilities of a maintainer
112+
* Determining strategy and policy for the project
113+
* Participating in, and leading, community meetings
114+
* Requirements
115+
* Experience as a Maintainer for at least 3 months
116+
* Demonstrates a broad knowledge of all components, repositories, and subprojects of the Podman project.
117+
* Is able to exercise judgment for the good of the project, independent of their employer, friends, or team
118+
* Mentors new Maintainers and Core Maintainers
119+
* Able to make decisions and contributions affecting the whole project, including multiple subprojects and repositories
120+
* Can commit to maintaining a high level of contribution to the project as a whole
121+
* Additional privileges:
122+
* Represent the project in public as a senior project member
123+
* Communicate with the CNCF on behalf of the project
124+
* Have a vote in Core Maintainer decision-making meetings
125+
126+
#### Process of becoming a Core Maintainer Member:
127+
1. A current maintainer must be sponsored by Core Maintainer. The Core Maintainer will open a PR against the main Podman repository and add the nominee as a Core Maintainer in the MAINTAINERS.md file.
128+
2. The nominee will add a comment to the PR confirming that they agree to all requirements and responsibilities of becoming a Core Maintainer.
129+
3. A majority of the current Core Maintainers must then approve the PR.
130+
4. If, for some reason, all existing members are inactive according to the Inactivity policy below or there are no Core Maintainers due to resignations, a supermajority vote of maintainers can bypass this process and approve new Core Maintainers directly.
131+
132+
### Community Manager
133+
Community managers are responsible for the project’s community interactions, including project social media, website maintenance, gathering metrics, managing the new contributor process, ensuring documentation is easy to use and welcoming to new users, and managing the project’s interactions with the CNCF. This is a nontechnical role, and as such does not require technical contribution to the project.
134+
135+
* Responsibilities include:
136+
* Participating in CNCF maintainer activities
137+
* Arranging, participating in, and leading, community meetings
138+
* Managing the project website and gathering associated metrics
139+
* Managing the project’s social media accounts and mailing lists and gathering associated metrics
140+
* Requirements
141+
* Sustained high level of contribution to the community, including attending and engaging in community meetings, contributions to the website, and contributions to documentation, for at least six months
142+
* Is able to exercise judgment for the good of the project, independent of their employer, friends, or team
143+
* Can commit to maintaining a high level of contribution to the project's community, website, and social media presence
144+
* Advocates for the community in Maintainer and Core Maintainer meetings
145+
* Additional privileges:
146+
* Represent the project in public
147+
* Communicate with the CNCF on behalf of the project
148+
* Have a voice, but not a vote, in Core Maintainer decision-making meetings
149+
150+
#### Process of becoming a Community Manager:
151+
1. Community Managers must be sponsored by a Core Maintainer. The Core Maintainer will open a PR against the main Podman repository and add the nominee as a Community Manager in the MAINTAINERS.md file.
152+
2. The nominee will add a comment to the PR confirming that they agree to all requirements and responsibilities of becoming a Community Manager.
153+
3. A majority of the current Core Maintainers must then approve the PR.
154+
155+
### Emeritus Maintainer
156+
Emeritus Maintainers are former Maintainers or Core Maintainers whose status has lapsed, either voluntarily or through inactivity. We recognize that these former maintainers still have valuable experience and insights, and maintain Emeritus status as a way of recognizing this. Emeritus Maintainer also offers a fast-tracked path to becoming a Maintainer again, should the contributor wish to return to the project.
157+
158+
Emeritus Maintainers have no responsibilities or requirements beyond those of an ordinary Contributor.
159+
160+
#### Process of becoming an Emeritus Maintainer:
161+
1. A current Maintainer or Core Maintainer may voluntarily resign from their position by making a pull request changing their role in the OWNERS file. They may choose to remove themselves entirely or to change their role to Emeritus Maintainer.
162+
2. Maintainers and Core Maintainers removed due to the Inactivity policy below may be moved to Emeritus Status.
163+
164+
## Maintainers File
165+
166+
The definitive source of truth for maintainers of a repository is the MAINTAINERS.md file in that repository. The MAINTAINERS.md file in the main Podman repository is used for project-spanning roles, including Core Maintainer and Community Manager. Some repositories in the project will also have an OWNERS file, used by the CI system to map users to roles. Any changes to the OWNERS file must make a corresponding change to the MAINTAINERS.md file to ensure that file maintains up to date. Most changes to MAINTAINERS.md will require a change to the repository’s OWNERS file (e.g. adding a Reviewer) but some will not (e.g. promoting a Maintainer to a Core Maintainer, which comes with no additional CI-related privileges).
167+
168+
## Inactivity
169+
170+
* Inactivity is measured by one or more of the following:
171+
* Periods of no contribution of code, pull request review, or participation in issue triage for longer than 12 months
172+
* Periods of no communication for longer than 3 months
173+
* Consequences of being inactive include:
174+
* Involuntary removal or demotion
175+
* Being asked to move to Emeritus status
176+
177+
## Involuntary Removal or Demotion
178+
179+
Involuntary removal/demotion of a contributor happens when responsibilities and requirements aren't being met. This may include repeated patterns of inactivity, an extended period of inactivity, a period of failing to meet the requirements of your role, and/or a violation of the Code of Conduct. This process is important because it protects the community and its deliverables while also opening up opportunities for new contributors to step in.
180+
181+
Involuntary removal or demotion of Maintainers and Reviewers is handled through a vote by a majority of the current Maintainers. Core Maintainers may be involuntarily removed by a majority vote of current Core Maintainers or, if all Core Maintainers have stepped down or are inactive according to the inactivity policy, by a supermajority (66%) vote of maintainers.
182+
183+
## Stepping Down/Emeritus Process
184+
If and when contributors' commitment levels change, contributors can consider stepping down (moving down the contributor ladder) vs moving to emeritus status (completely stepping away from the project).
185+
186+
Maintainers and Reviewers should contact the Maintainers about changing to Emeritus status, or reducing your contributor level. Core Maintainers should contact other Core Maintainers.
187+
188+
## Updates to this document
189+
Updates to this Governance document require approval from a majority vote of the Core Maintainers.
190+
191+
## Contact
192+
* For inquiries, please reach out to:
193+
* [Tom Sweeney, Community Manager](tsweeney@redhat.com)

‎MAINTAINERS.md

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Podman Maintainers
2+
3+
[GOVERNANCE.md](https://github.com/containers/podman/blob/main/GOVERNANCE.md)
4+
describes the Podman project's governance and the Project Roles used below.
5+
6+
## Maintainers
7+
8+
| Maintainer | GitHub ID | Project Roles | Affiliation |
9+
|-------------------|----------------------------------------------------------|----------------------------------|----------------------------------------------|
10+
| Brent Baude | [baude](https://github.com/baude) | Core Maintainer | [Red Hat](https://github.com/RedHatOfficial) |
11+
| Ygal Blum | [ygalblum](https://github.com/ygalblum) | Maintainer | [Red Hat](https://github.com/RedHatOfficial) |
12+
| Jake Correnti | [jakecorrenti](https://github.com/jakecorrenti) | Reviewer | [Red Hat](https://github.com/RedHatOfficial) |
13+
| Ashley Cui | [ashley-cui](https://github.com/ashley-cui) | Maintainer | [Red Hat](https://github.com/RedHatOfficial) |
14+
| Nalin Dahyabhai | [nalind](https://github.com/nalind) | Core Maintainer | [Red Hat](https://github.com/RedHatOfficial) |
15+
| Jason Greene | [n1hility](https://github.com/n1hility) | Reviewer | [Red Hat](https://github.com/RedHatOfficial) |
16+
| Matthew Heon | [mheon](https://github.com/mheon) | Core Maintainer | [Red Hat](https://github.com/RedHatOfficial) |
17+
| Paul Holzinger | [luap99](https://github.com/Luap99) | Core Maintainer | [Red Hat](https://github.com/RedHatOfficial) |
18+
| Jhon Honce | [jwhonce](https://github.com/jwhonce) | Reviewer | [Red Hat](https://github.com/RedHatOfficial) |
19+
| Mario Loriedo | [l0rd](https://github.com/l0rd/) | Maintainer | [Red Hat](https://github.com/RedHatOfficial) |
20+
| Lokesh Mandvekar | [lsm5](https://github.com/lsm5) | Maintainer | [Red Hat](https://github.com/RedHatOfficial) |
21+
| Urvashi Mohnani | [umohnani8](https://github.com/umohnani8) | Reviewer | [Red Hat](https://github.com/RedHatOfficial) |
22+
| Aditya Rajan | [flouthoc](https://github.com/flouthoc) | Reviewer | [Red Hat](https://github.com/RedHatOfficial) |
23+
| Valentin Rothberg | [vrothberg](https://github.com/vrothberg) | Reviewer | [Red Hat](https://github.com/RedHatOfficial) |
24+
| Giuseppe Scrivano | [giuseppe](https://github.com/giuseppe) | Core Maintainer | [Red Hat](https://github.com/RedHatOfficial) |
25+
| Neil Smith | [Neil-Smith](https://github.com/Neil-Smith) | Community Manager | [Red Hat](https://github.com/RedHatOfficial) |
26+
| Tom Sweeney | [TomSweeneyRedHat](https://github.com/TomSweeneyRedHat/) | Maintainer and Community Manager | [Red Hat](https://github.com/RedHatOfficial) |
27+
| Miloslav Trmač | [mtrmac](https://github.com/mtrmac) | Core Maintainer | [Red Hat](https://github.com/RedHatOfficial) |
28+
| Dan Walsh | [rhatdan](https://github.com/rhatdan) | Reviewer | [Red Hat](https://github.com/RedHatOfficial) |
29+
30+
## Alumni
31+
32+
None at present
33+
34+
## Credits
35+
36+
The structure of this document was based off of the equivalent one in the [CRI-O Project](https://github.com/cri-o/cri-o/blob/main/MAINTAINERS.md).

‎OWNERS

-2
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,10 @@ approvers:
99
- mheon
1010
- mtrmac
1111
- rhatdan
12-
- vrothberg
1312
- ygalblum
1413
reviewers:
1514
- Luap99
1615
- TomSweeneyRedHat
17-
- alexlarsson
1816
- baude
1917
- flouthoc
2018
- giuseppe

‎REVIEWING.md

+108
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Reviewing Pull Requests
2+
3+
This document contains general principles for how to perform code reviews in the Podman repository.
4+
It does not aim to be a complete guide to how to perform code review, but rather to provide general guidance on how code reviews should be performed.
5+
6+
This document is aimed at Reviewers, Maintainers, and Core Maintainers (see [GOVERNANCE.md](./GOVERNANCE.md) for definitions of these roles), but these guidelines should be followed by all who wish to review code in the Podman project's Github repositories, even those who are not currently a maintainer.
7+
8+
## How are reviews performed
9+
10+
The Podman project aims to ensure that all PRs are reviewed by at least 2 people prior to merge, at least one of which must be a repository Maintainer.
11+
There are some exceptions to this: Updates to libraries (including Go vendor updates) that pass CI cleanly and require no code changes may be merged by a maintainer without further review.
12+
13+
All code merged must pass CI.
14+
15+
## What should you review?
16+
17+
We encourage review of all PRs, even those not in the area of expertise of the reviewer.
18+
Even if you are not fully familiar with the code in question, you can still notice basic mistakes.
19+
Feel free to ask questions about how areas of the code work to help familiarize yourself during reviews.
20+
If you finish a review and do not feel like you adequately understood the code to approve it for merge, tag an expert in that area of the code to perform a further review.
21+
22+
Timely PR reviews are important - contributors can become discouraged if a PR is neglected by maintainers.
23+
All Maintainers and Reviewers should try to review new pull requests in their repositories once a day to ensure this.
24+
When you review a PR with failing tests, please check to see if those tests failed due to known flakes.
25+
If so, please restart the failed tests.
26+
Many repositories in the Podman project can only have their tests restarted by project members, not the submitter, so regular attention to test failures by reviewers is important.
27+
28+
## Things to Check
29+
30+
### Breaking Changes
31+
32+
The Podman project aims to present a stable API for its users.
33+
Breaking changes to the project's Command Line Interfaces or public APIs (the Podman REST API and its associated bindings) must only be made in approved breaking change releases - Podman 6.0, 7.0, etc.
34+
Breaking changes can include renaming an option without retaining the original name as an alias, removing an option entirely, or changing how an option works in a way that does not ensure backwards compatibility.
35+
36+
Periods when it is acceptable to merge breaking changes will be widely announced.
37+
If it is not one of those periods, reviewers should be on the lookout for breaking changes.
38+
PRs with breaking changes should not be merged.
39+
Please guide the contributor in how to make the change in a non-breaking fashion.
40+
If this is not possible, deferring the PR to the next breaking change window or closing it entirely is appropriate.
41+
42+
### Commit Messages and Hygiene
43+
44+
Good commit messages are essential for understanding why a change was made in the future.
45+
Reviewers should check each commit of a PR to ensure that it has an appropriate commit message which fully and accurately explains the change and why it is being made.
46+
This should remain true after changes to the PR due to code review, so please re-review commit messages before merging code, to ensure they are still accurate.
47+
48+
Each commit in a PR should be self-contained and have a clear and distinct purpose.
49+
If this is not true, please encourage the contributor to squash their commits using `git rebase -i` until it is true.
50+
51+
### Disagreements between reviewers
52+
53+
We do not expect all reviewers to be of the same opinion during code review.
54+
If you see another reviewer requesting changes to a PR you do not agree with, it is perfectly acceptable to comment to that effect.
55+
Disagreements between maintainers can generally be worked out during PR review through comments.
56+
If this is not possible, other maintainers can be called on to give their opinions and determine a way forward.
57+
We encourage such disagreements and discussions, so long as they remain respectful.
58+
59+
Being respectful includes respect for the contributor's time.
60+
If there is a disagreement, please do not make the contributor make repeated changes until an agreement on how to proceed is reached.
61+
Also, please attempt to reach an agreement quickly, so the PR can be merged in a timely fashion.
62+
63+
### Language Version Updates
64+
65+
Most repositories in the Podman project are written in Go, and as such target a specific version of Go in their `go.mod`.
66+
For example:
67+
```
68+
$ cat go.mod | grep 'go 1.'
69+
go 1.22.8
70+
```
71+
72+
For all branches except the main branch, this should always remain static.
73+
PRs into a non-main branch which change the supported Go version should be modified to not require such a change, or rejected if that is not possible.
74+
Changing supported Go version in the main branch is allowed, but not encouraged.
75+
Doing so will require significant discussion among maintainers, as it can affect what distributions the main branch can be built.
76+
77+
### Tests
78+
79+
Please Check tests added by the PR.
80+
If a PR has no new tests, determine if this is actually appropriate - has new functionality been added which should have been tested?
81+
If the PR does have tests, check to see if they are reasonably comprehensive.
82+
The Podman Project does not have code coverage standards at present, but we aim to ensure that all new functionality is tested.
83+
84+
### Documentation
85+
86+
All changes to public-facing APIs (e.g. the Podman REST API) and CLI should be appropriately documented.
87+
API changes require Swagger documentation.
88+
CLI changes should be documented in the Manpages.
89+
90+
Please validate that PRs making such changes include appropriate documentation.
91+
Many repositories in the Podman project will enforce this via CI check, but you should still review the contents of the documentation to make sure they are appropriate and complete.
92+
93+
## Things to Avoid
94+
95+
### Bikeshedding and excessively critical reviews
96+
97+
Please avoid bikeshedding during reviews.
98+
99+
Trivial changes that do not affect the ultimate functionality of the PR - for example, small grammar or phrasing changes in documentation, unnecessary renaming of variables - should not block merge of a PR.
100+
It is acceptable to make such comments, but they should be marked as nice to have changes.
101+
102+
### Asking for unrelated changes
103+
104+
Please do not request that a contributor make significant changes to code their PR did not touch.
105+
If you are reviewing and find problems in pre-existing code in a file that the PR changed, you should not require that the contributor change this code as well.
106+
Asking if they are willing to do so is fine, but do not block merge of the PR if they are unwilling.
107+
108+
Instead, consider asking them to add a comment with a "TODO" or "FIXME" to the area that needs changing (or making a PR yourself with such a comment).

0 commit comments

Comments
 (0)
Please sign in to comment.