Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

MAINTAINERS_GUIDE: introduce guidance on maintainer expectations #935

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+91 −0
Open

MAINTAINERS_GUIDE: introduce guidance on maintainer expectations #935

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
91 changes: 91 additions & 0 deletions MAINTAINERS_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# 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, please submit a change!
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this document a governance document or just an informational document? If it's the former we should mention that changes require a 2/3rd LGTM.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good question. Seems like a typo would be silly to have 2/3 LGTM, but otherwise it is like a governance doc.


## What are responsibilities of a maintainer?

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) Respect and uphold 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.
A 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` (or using the "Approve" feature in GitHub PR reviews).
However, only currently listed `MAINTAINERS` are counted towards the required **two LGTMs**.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We often run into situations where it's a maintainer who's opened a PR and it's unclear whether their "self-LGTM" counts towards the two or not -- should we continue to handle these case-by-case, or do any maintainers think it's worth explicitly calling out one way or the other directly in the guide?

Similarly, should we call out "trivial URL fix" exceptions like opencontainers/runtime-spec#1157 explicitly, or continue to handle those case-by-case as well?

(I don't have any strong opinions on either of these one way or another, just things that come to mind while I'm reading the doc.)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a way in the github approval process to reduce the LGTM is the PR is from a maintainer?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You cannot self-LGTM with GitHub reviews, so if we require GitHub reviews then maintainers already cannot self-LGTM. But we should have an explicit statement whether self-LGTMs are allowed (I've gone back and forth on the issue over the years, but there should be a statement of what the rule is so we're all on the same page).


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 view 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 at least **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**.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider changing this from "current" to "voting" so that if maintainers do not vote within the 10 day period, they are not counted in the 2/3 majority threshold. This would better prepare the project if several maintainers go inactive and we cannot get 2/3 of all maintainers to respond to a vote.

We should also allow a maintainer to step down themselves, without a vote.

Copy link
Member Author

@vbatts vbatts Aug 10, 2022 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm, I could see that getting tricky. I'm not favor of that strict of change regarding those that voted or abstained.

But yes to folks can step down without the 2/3 vote. Maybe in that case, it's just the 2 LGTM to approve a maintainer's resignation?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The quorum problem is a weird one to solve generically... but maybe to mitigate the "multiple inactive maintainers" scenario we could introduce some requirement around activity/responsiveness? if someone doesn't respond for 6 months they're removed as a maintainer? not sure

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

right. "Active" is PR review, issue comments or creation, slack/mailing-list participation, joining calls?
Seems tricksy to track without a bot.

so if a maintainer is deemed inactive, then their vote counts for less? or they can be remove with less than 2/3 quorum?

Copy link
Member

@cyphar cyphar Aug 11, 2022 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My personal view is that the quorum rules should be the same for all governance votes because otherwise you may end up with weird cases where we could rule-lawyer ourselves into weird situations.

The rest of the OCI (both projects and the TOB) use qualified super-majority votes (2/3 of all seats, with abstaining seats counted as being against the motion) so I don't feel particularly comfortable with changing the rules for this one governance procedure in one project. A project with healthy maintainership that has a single maintainer they wish to remove should not have any issues getting a 2/3 vote if that is what the will of the project is. I'm also not sure that a maintainer being on vacation for a few weeks (as I am now) is reasonable grounds to reduce the level of review necessary for what is effectively a governance change.

If we are continuing to have inactive maintainer issues such that such a mechanism cannot work, then we should solve it by removing inactive maintainers (I am aware that I would probably be included under that label as I haven't been involved in the more recent image signing and related work) and being more assertive about it than last time.

But that's just my 2 cents.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be useful to have a state between active and removed? Allow a maintainer to be marked as inactive if they aren't responding for X months, so that 2/3rd majorities aren't impossible to achieve. But those inactive maintainers could be easily reactivated if they later returned. Perhaps a 2 active maintainer vote to move someone between active and inactive, but 2/3rds of active maintainers to remove a maintainer or perform other large changes.

I think a policy to handle these situations would be useful in lots of open source governance docs, not just in image-spec. People change jobs or have major life changes that result in us going quiet. And if routine updates still happen with the existing moderators, no one notices until a major change is needed.

The voting period is at least **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.