Skip to content

Commit

Permalink
MAINTAINERS_GUIDE: introduce guidance on maintainer expectations
Browse files Browse the repository at this point in the history
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 <vbatts@hashbangbash.com>
  • Loading branch information
vbatts committed Aug 9, 2022
1 parent 6ad7100 commit 1e6b5e0
Showing 1 changed file with 90 additions and 0 deletions.
90 changes: 90 additions & 0 deletions MAINTAINERS_GUIDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Maintainers Guide

## Introduction

Dear maintainer,
Thank you for investing the time and energy to help make this project as useful as possible.
Maintaining a project is difficult, sometimes unrewarding work.
Sure, you will get to contribute cool features to the project.
But most of your time will be spent reviewing, cleaning up, documenting, answering questions, justifying design decisions - while everyone has all the fun!
But remember - the quality of the maintainers work is what distinguishes the good projects from the great.
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.

This document is a manual for maintainers old and new.
It explains what is expected of maintainers, how they should work, and what tools are available to them.

This is a living document - if you see something out of date or missing, speak up!

## What are a maintainer's responsibility?

It is every maintainer's responsibility to:

1) Expose a clear roadmap for improvements for the project.
2) Deliver prompt feedback and decisions on pull requests.
3) Be available to anyone with questions, bug reports, criticism etc. on their component.
This includes Slack, mailing-list, and GitHub issues and pull requests.
4) Make sure to respect the philosophy, design, compatibility considerations, and roadmap of the project.

## How are decisions made?

Short answer: with pull requests to this repository.

This is an open-source project with an open design philosophy.
This means that the repository is the source of truth for EVERY aspect of the project, including its philosophy, design, roadmap and APIs.
*If it's part of the project, it's in the repo.
It's in the repo, it's part of the project.*

As a result, all decisions can be expressed as changes to the repository.
An spec change is a change to the specification.
An implementation change is a change to the source code.
A philosophy change is a change to the philosophy manifesto.
And so on.

All decisions affecting this project, big and small, follow the same 3 steps:

* Step 1: Open a pull request. Anyone can do this.

* Step 2: Discuss the pull request. Anyone can do this.

* Step 3: Accept (`LGTM`) or refuse a pull request. The relevant maintainers do this (see below "Who decides what?")

*I'm a maintainer, should I make pull requests too?*

Yes.
Nobody should ever push to the `main` branch directly.
All changes should be made through a pull request.

Bigger changes (that may span projects): an [OCI Working Group](https://github.com/opencontainers/tob/blob/main/CHARTER.md) may be needed.

## Who decides what?

All decisions are pull requests, and the relevant maintainers make decisions by accepting or refusing the pull request.
Review and acceptance by anyone is denoted by adding a comment in the pull request: `LGTM`.
However, only currently listed `MAINTAINERS` are counted towards the required **two LGTMs**.

Overall the maintainer system works because of mutual respect across the maintainers of the project.
The maintainers trust one another to make decisions in the best interests of the project.
Sometimes maintainers can disagree and this is part of a healthy project to represent the point of views of various people.

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.
It is expected that this would be a very exceptional event.

## How are maintainers added?

The best maintainers have a vested interest in the project.
Maintainers are first and foremost contributors that have shown they are committed to the long term success of the project.
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.

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.
The final vote to add a new maintainer should be approved by over **66% (2/3) of the current maintainers**.
The voting period is **five business days** on the Pull Request to add the new maintainer.

## What is expected of maintainers?

Part of a healthy project is to have active maintainers to support the community in contributions and perform tasks to keep the project running.
Maintainers are expected to be able to respond in a timely manner if their help is required on specific issues where they are pinged.
Being a maintainer is a time consuming commitment and should not be taken lightly.

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**.
The voting period is **ten business days**.
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 comments on commit 1e6b5e0

Please sign in to comment.