Skip to content

Commit 6b9b7d2

Browse files
committed
MAINTAINERS_GUIDE: introduce guidance on maintainer expectations
This is adopted from https://github.com/opencontainers/runc/blob/602c85fdc6c73d614213fc1759f8e710e54047ca/MAINTAINERS_GUIDE.md Notably: - making the "runc" into a more generic "this project" - dropping the concept of "chief maintainer" - formatting to a sentence per line Signed-off-by: Vincent Batts <[email protected]>
1 parent f3096cf commit 6b9b7d2

File tree

1 file changed

+90
-0
lines changed

1 file changed

+90
-0
lines changed

MAINTAINERS_GUIDE.md

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Maintainers Guide
2+
3+
## Introduction
4+
5+
Dear maintainer,
6+
Thank you for investing the time and energy to help make this project as useful as possible.
7+
Maintaining a project is difficult, sometimes unrewarding work.
8+
Sure, you will get to contribute cool features to the project.
9+
But most of your time will be spent reviewing, cleaning up, documenting, answering questions, justifying design decisions - while everyone has all the fun!
10+
But remember - the quality of the maintainers work is what distinguishes the good projects from the great.
11+
So please be proud of your work, even the unglamorous parts, and encourage a culture of appreciation and respect for *every* aspect of improving the project - not just the hot new features.
12+
13+
This document is a manual for maintainers old and new.
14+
It explains what is expected of maintainers, how they should work, and what tools are available to them.
15+
16+
This is a living document - if you see something out of date or missing, speak up!
17+
18+
## What are a maintainer's responsibility?
19+
20+
It is every maintainer's responsibility to:
21+
22+
1) Expose a clear roadmap for improvements for the project.
23+
2) Deliver prompt feedback and decisions on pull requests.
24+
3) Be available to anyone with questions, bug reports, criticism etc. on their component.
25+
This includes Slack, mailing-list, and GitHub issues and pull requests.
26+
4) Make sure to respect the philosophy, design, compatibility considerations, and roadmap of the project.
27+
28+
## How are decisions made?
29+
30+
Short answer: with pull requests to this repository.
31+
32+
This is an open-source project with an open design philosophy.
33+
This means that the repository is the source of truth for EVERY aspect of the project, including its philosophy, design, roadmap and APIs.
34+
*If it's part of the project, it's in the repo.
35+
It's in the repo, it's part of the project.*
36+
37+
As a result, all decisions can be expressed as changes to the repository.
38+
A spec change is a change to the specification.
39+
An implementation change is a change to the source code.
40+
A philosophy change is a change to the philosophy manifesto.
41+
And so on.
42+
43+
All decisions affecting this project, big and small, follow the same 3 steps:
44+
45+
* Step 1: Open a pull request. Anyone can do this.
46+
47+
* Step 2: Discuss the pull request. Anyone can do this.
48+
49+
* Step 3: Accept (`LGTM`) or refuse a pull request. The relevant maintainers do this (see below "Who decides what?")
50+
51+
*I'm a maintainer, should I make pull requests too?*
52+
53+
Yes.
54+
Nobody should ever push to the `main` branch directly.
55+
All changes should be made through a pull request.
56+
57+
Bigger changes (that may span projects): an [OCI Working Group](https://github.com/opencontainers/tob/blob/main/CHARTER.md) may be needed.
58+
59+
## Who decides what?
60+
61+
All decisions are pull requests, and the relevant maintainers make decisions by accepting or refusing the pull request.
62+
Review and acceptance by anyone is denoted by adding a comment in the pull request: `LGTM`.
63+
However, only currently listed `MAINTAINERS` are counted towards the required **two LGTMs**.
64+
65+
Overall the maintainer system works because of mutual respect across the maintainers of the project.
66+
The maintainers trust one another to make decisions in the best interests of the project.
67+
Sometimes maintainers can disagree and this is part of a healthy project to represent the point of views of various people.
68+
69+
The maintainer system is built on trust, if there is a conflict the maintainers do not agree on it can be brought to the [technical oversight board](https://github.com/opencontainers/tob) for resolution.
70+
It is expected that this would be a very exceptional event.
71+
72+
## How are maintainers added?
73+
74+
The best maintainers have a vested interest in the project.
75+
Maintainers are first and foremost contributors that have shown they are committed to the long term success of the project.
76+
Contributors wanting to become maintainers are expected to be deeply involved in contributing code, pull request review, and triage of issues in the project for more than two months.
77+
78+
Just contributing does not make you a maintainer, it is about building trust with the current maintainers of the project and being a person that they can depend on and trust to make decisions in the best interest of the project.
79+
The final vote to add a new maintainer should be approved by over **66% (2/3) of the current maintainers**.
80+
The voting period is at least **five business days** on the Pull Request to add the new maintainer.
81+
82+
## What is expected of maintainers?
83+
84+
Part of a healthy project is to have active maintainers to support the community in contributions and perform tasks to keep the project running.
85+
Maintainers are expected to be able to respond in a timely manner if their help is required on specific issues where they are pinged.
86+
Being a maintainer is a time consuming commitment and should not be taken lightly.
87+
88+
When a maintainer is unable to perform the required duties they can be removed with a vote by **66% (2/3) of the current maintainers**.
89+
The voting period is at least **ten business days**.
90+
Issues related to a maintainer's performance should be discussed with them among the other maintainers so that they are not surprised by a pull request removing them.

0 commit comments

Comments
 (0)