This document defines the project governance for Pinniped.
# Overview
**Pinniped** is committed to building an open, inclusive, productive and self-governing open source community focused on building authentication services for Kubernetes clusters. The
community is governed by this document which defines how all members should work together to achieve this goal.
# Code of Conduct
The Pinniped community abides by this [code of conduct](https://github.com/vmware-tanzu/pinniped/blob/main/CODE_OF_CONDUCT.md).
# Community Roles
* **Users:** Members that engage with the Pinniped community via any medium (Slack, GitHub, mailing lists, etc.).
* **Contributors:** Do regular contributions to the Pinniped project (documentation, code reviews, responding to issues, participating in proposal discussions, contributing code, etc.).
* **Maintainers:** Responsible for the overall health and direction of the project. They are the final reviewers of PRs and responsible for Pinniped releases.
# Maintainers
New maintainers must be nominated by an existing maintainer and must be elected by a supermajority of existing maintainers. Likewise, maintainers can be removed by a supermajority of the existing maintainers or can resign by notifying one of the maintainers.
**Note:** If a maintainer leaves their employer they are still considered a maintainer of Pinniped, unless they voluntarily resign. Employment is not taken into consideration when determining maintainer eligibility unless the company itself violates our [Code of Conduct](https://github.com/vmware-tanzu/pinniped/blob/main/CODE_OF_CONDUCT.md).
# Decision Making
Ideally, all project decisions are resolved by consensus. If impossible, any maintainer may call a vote. Unless otherwise specified in this document, any vote will be decided by a supermajority of maintainers.
A supermajority is defined as two-thirds of members in the group. A supermajority of maintainers is required for certain decisions as outlined in this document. A supermajority vote is equivalent to the number of votes in favor being at least twice the number of votes against. A vote to abstain equals not voting at all. For example, if you have 5 maintainers who all cast non-abstaining votes, then a supermajority vote is at least 4 votes in favor. Voting on decisions can happen on the mailing list, GitHub, Slack, email, or via a voting service, when appropriate. Maintainers can either vote "agree, yes, +1", "disagree, no, -1", or "abstain". A vote passes when supermajority is met.
Other maintainers may chime in and request additional time for review, but should remain cognizant of blocking progress and abstain from delaying progress unless absolutely needed. The expectation is that blocking progress is accompanied by a guarantee to review and respond to the relevant action in short order.
This is a short summary of the problem that exists, why it needs to be
solved: what specific needs are being met. Compelling problem statements
include concrete examples and use cases (even if only by reference).
How exactly the proposal would meet those needs should be located in the
"Proposal" section, not this one. The goal of this section is to help
readers quickly empathize with the target users' current experience to
motivate the proposed change.
### How Pinniped Works Today (as of version vX.X.X)
How Pinniped works today in the context of the problem statement.
This will typically detail how Pinniped falls short of supporting
the desired use case(s).
## Terminology / Concepts
Define any terms or concepts that are used throughout this proposal.
## Proposal
The primary content of the proposal. Subsections will explain how the
problem(s) will be addressed.
### Goals and Non-goals
A short list of what the goals of this proposal are and are not.
### Specification / How it Solves the Use Cases
Detailed explanation of the proposal's design. This will typically
also detail how the specification supports the desired use cases.
### Other Approaches Considered
Mention of other reasonable ways that the problem(s)
could be addressed with rationale for why they were less
desirable than the proposed approach.
## Open Questions
A list of questions that need to be answered.
## Answered Questions
A list of questions that have been answered.
```
## Proposal States
| Status | Definition |
| --- | --- |
| `draft` | The proposal is actively being written by the proposer. Not yet ready for review. |
| `in-review` | The proposal is being reviewed by the community and the project maintainers. |
| `accepted` | The proposal has been accepted by the project maintainers. |
| `rejected` | The proposal has been rejected by the project maintainers. |
## Lifecycle of a Proposal
1. Author adds a proposal by creating a PR in draft mode. (Authors can save their work until ready.)
2. When the author elaborates the proposal sufficiently to withstand critique they:
1. change the status to `in-review` and
2. mark the PR as "Ready for Review"
3. The community critiques the proposal by adding PR reviews in order to mature/converge on the proposal.
4. When the maintainers reach consensus or supermajority to accept a proposal, they:
1. change the status to `accepted`,
2. adjust the proposal number in the subdirectory's name if needed,
3. record both majority and dissenting opinions,
4. merge the PR, thus adding the new proposal to the `main` branch, and
5. code implementation PR(s) are submitted separately to implement the solution.
5. When the maintainers do not reach consensus or supermajority, then the proposal is rejected, and they:
1. may mark the status `rejected`, and
2. close the PR with a note explaining the rejection.
6. Rejected proposal PRs may be reopened and moved back to `in-review` if there are material changes to the proposal which address the reasons for rejection.
## Proposal Review
Once a proposal PR marked as "Ready for Review", the community and all project maintainers will review the proposal.
The goal of the review is to gain an understanding of the problem being solved and the design of the proposed solution.
Maintainers will consider all aspects of the proposed problem and solution, including but not limited to:
- Is the problem within scope for the project?
- Would the additional future cost of maintenance imposed by an implementation of the solution justify solving the problem?
- Is the solution reasonably consistent with the rest of the project?
- How does the solution impact the usability, security, scalability, performance, observability, and reliability of Pinniped?
- How might an implementation of the solution be architected and tested via automation?
- What risks might be introduced by an implementation of the solution?
- The opportunity cost of the time it would take to implement the solution, if the implementation is to be done by the maintainers.
## Maintenance of Accepted Proposal Documents
Proposal documents reflect a point-in-time design and decision.
Once approved, they become historical documents, not living documents.
There is no expectation that they will be maintained in the future. Instead, significant changes to a feature
which came from a previous proposal should be proposed as a fresh proposal. New proposals should link
to previous proposals for historical context when appropriate.
## Getting Help with the Proposal Process
Please reach out to the maintainers in the Kubernetes Slack Workspace within
the [#pinniped](https://kubernetes.slack.com/archives/C01BW364RJA) channel
or on the [Pinniped mailing list](mailto:project-pinniped@googlegroups.com) with any questions.
