|
| 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