doc: add new governance and contributor ladder model

Signed-off-by: Jan Larwig <jan@larwig.com>
This commit is contained in:
Jan Larwig 2025-10-04 16:40:54 +02:00
parent b24d85dfbf
commit 4dabaeb272
No known key found for this signature in database
GPG Key ID: C2172BFA220A037A
5 changed files with 500 additions and 21 deletions

45
.github/CODEOWNERS vendored
View File

@ -1,5 +1,31 @@
# Default owner should be a core org reviewers unless overridden by later rules in this file # OAuth2-Proxy CODEOWNERS
* @oauth2-proxy/reviewers # This file maps repository paths to GitHub teams for review.
# Syntax: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
# --- Core Maintainers (project-wide) ---
* @oauth2-proxy/maintainers
# --- Core ---
* @oauth2-proxy/core-reviewers
# --- Documentation ---
docs/ @oauth2-proxy/documentation-reviewers
# --- CI / Testing ---
.devcontainer/ @oauth2-proxy/ci-reviewers
.github/ @oauth2-proxy/ci-reviewers
.vscode/ @oauth2-proxy/ci-reviewers
contrib/ @oauth2-proxy/ci-reviewers
go.mod @oauth2-proxy/ci-reviewers
go.sum @oauth2-proxy/ci-reviewers
# --- Configuration / API ---
contrib/ @oauth2-proxy/api-reviewers
pkg/apis/ @oauth2-proxy/api-reviewers
# --- Provider ---
providers/ @oauth2-proxy/provider-reviewers
# login.gov provider # login.gov provider
# Note: If @timothy-spencer terms out of his appointment, your best bet # Note: If @timothy-spencer terms out of his appointment, your best bet
@ -7,17 +33,4 @@
# in the login.gov team (https://login.gov/developers/), the cloud.gov team # in the login.gov team (https://login.gov/developers/), the cloud.gov team
# (https://cloud.gov/docs/help/), or the 18F org (https://18f.gsa.gov/contact/ # (https://cloud.gov/docs/help/), or the 18F org (https://18f.gsa.gov/contact/
# or the public devops channel at https://chat.18f.gov/). # or the public devops channel at https://chat.18f.gov/).
providers/logingov.go @timothy-spencer providers/logingov.* @oauth2-proxy/provider-login-gov-reviewers
providers/logingov_test.go @timothy-spencer
# Bitbucket provider
providers/bitbucket.go @aledeganopix4d
providers/bitbucket_test.go @aledeganopix4d
# Nextcloud provider
providers/nextcloud.go @Ramblurr
providers/nextcloud_test.go @Ramblurr
# DigitalOcean provider
providers/digitalocean.go @kamaln7
providers/digitalocean_test.go @kamaln7

268
CONTRIBUTOR_LADDER.md Normal file
View File

@ -0,0 +1,268 @@
# OAuth2-Proxy Contributor Ladder
This document defines the roles, responsibilities, advancement criteria,
inactivity process, and interim role policies for OAuth2-Proxy contributors.
It extends the standard Kubernetes-style ladder with **specialty tracks** so
contributors can grow within their focus areas.
---
## Roles
### 1) Contributor
Anyone making contributions of any kind (code, docs, tests, CI configs, security
reports, reviews, triage, discussions).
**Requirements**
- For code changes all commits need to be Signed-Off by you. This is enforced
through the [DCO GitHub App](https://github.com/apps/dco)
- Follow the OAuth2-Proxy/CNCF [Code of Conduct](CODE_OF_CONDUCT.md)
**Privileges**
- Recognized as an active community member
- Eligible for nomination to **Member**
---
### 2) Member
Regular contributors engaged with the project for at least **3 months**.
**Requirements**
- Self nomination by the contributor via a GitHub Issue.
- Must be Sponsored/Approved by **two Core Maintainers** (sponsorship ask must
happen within the GitHub issue by tagging the sponsors).
- Substantive contributions (code, docs, tests, reviews, triage) in the last
3 months.
**Privileges**
- Added to the GitHub `members` team.
- Can be assigned issues and PRs.
- Eligible for **Reviewer** nomination.
---
### 3) Reviewer (per Specialty)
Experienced contributors who review changes in **one or more specialties**.
**Requirements**
- Member for at least **3 months**.
- Regular, high-quality reviews in the specialty.
- Several meaningful Issue or PR reviews over the last 3 months.
**Privileges**
- Listed as `reviewer` in the relevant `OWNERS` files.
- May use `/lgtm` on PRs within the specialty.
- Eligible for **Maintainer** nomination.
> A contributor may hold different roles across specialties
(e.g., **Reviewer** in Provider Integrations, **Member** in Core Proxy).
---
### 4) Maintainer (Project-Wide)
Project leaders with governance, release, and cross-specialty responsibility.
**Requirements**
- Reviewer for at least **6 months** in one or more specialties.
- Demonstrated leadership, reliability, and constructive collaboration.
- Nominated and approved by a **simple majority** of Maintainers.
**Privileges**
- GitHub admin rights as needed.
- Release management authority.
- Representation within CNCF.
---
## Specialty Tracks
Specialties define scope for `reviewer` permissions and expectations.
### Core Proxy
Focus: Main proxy functionality, request handling, session management,
authentication flow, and security implementation.
**Key Responsibilities:**
- Review core proxy changes in files like `oauthproxy.go`, `main.go`, and `validator.go`
- Ensure adherence to [OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)
and [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) specifications
- Validate security implementations, including session management, token
validation, and secure cookie handling
- Review authentication and authorization flow implementations
- Ensure proper handling of edge cases and security vulnerabilities
### Provider Integrations
Focus: OAuth/OIDC provider integrations in the `providers/` directory.
**Key Responsibilities:**
- Review provider-specific code changes in the `providers/` directory
- Ensure conformance to OAuth/OIDC standards and provider-specific requirements
- Coordinate breaking changes for provider implementations
- Review provider configuration documentation
- Validate provider test implementations
### Configuration / API
Focus: Configuration options, API changes, and example configurations.
**Key Responsibilities:**
- Review configuration-related code and documentation
- Ensure backward compatibility of configuration options
- Review example configurations in the `contrib/` directory
- Validate CLI argument parsing and validation
### Helm Chart & Kubernetes
Focus: Helm chart in the separate `oauth2-proxy/manifests` repository and
Kubernetes deployment configurations.
**Key Responsibilities:**
- Review Helm chart templates and values
- Ensure Kubernetes best practices in deployment configurations
- Validate Helm chart testing and CI integration
- Review Kubernetes-related documentation
### Documentation
Focus: Documentation in the `docs/` directory, including configuration guides,
provider documentation, and tutorials.
**Key Responsibilities:**
- Review documentation changes for accuracy and clarity
- Ensure documentation is kept in sync with code changes
- Review provider-specific documentation
- Validate example configurations and tutorials
- Review versioning and release documentation
### CI / Automation
Focus: Test implementations and CI/CD workflows across repositories.
**Key Responsibilities:**
- Review integration and E2E tests
- Ensure adequate test coverage for new features
- Review CI/CD workflows in `.github/workflows/`
- Validate test infrastructure and test data
- Review test automation and reporting
### Community
Focus: Community nurturing, issue triage, and user support.
**Key Responsibilities:**
- Help with issue triage and support requests
- Monitor community channels (Slack, GitHub Discussions)
- Organize community talks and events
- Promote OAuth2-Proxy in the community
- Create demos and tutorials for users
- Foster a welcoming environment for new contributors
---
### Specialty Advancement
Contributors can advance in multiple specialties simultaneously. For example:
- A contributor could be a **Reviewer** in Provider Integrations and a **Member** in Core Proxy
- A contributor could be a **Reviewer** in both Helm Chart & Kubernetes and Testing & CI
This allows contributors to focus on areas where they have expertise while still contributing to other parts of the project.
---
## Member Abuse
Abuse of project resources is a serious violation of our community standards and
will not be tolerated. This includes but is not limited to:
* Using project infrastructure for unauthorized activities.
* Misusing project funds or financial resources.
* Gaining unauthorized access to or damaging project infrastructure.
* Willingly engaging in activities that are against the Code of Conduct.
* Willingly introducing malware or viruses to the project's infrastructure or codebase.
* Any other activity that jeopardizes the project's resources, reputation, or community members.
### Procedure for Handling Abuse
1. **Immediate Revocation of Privileges**: If abuse is suspected, any maintainer
can immediately revoke the member's access to all project infrastructure and
resources to prevent further damage. This is a precautionary measure and not a
final judgment.
2. **Investigation**: The maintainers will conduct a private investigation to
gather all relevant facts and evidence. The accused member will be given an
opportunity to respond to the allegations.
3. **Decision**: Based on the investigation, the maintainers will determine if a
violation has occurred.
4. **Consequences**: If a violation is confirmed, consequences will be applied,
which may include:
- Permanent removal from the project.
- Reporting the user to GitHub and other relevant platforms.
- In cases of financial misuse or illegal activities, reporting to law
enforcement authorities.
All actions taken will be documented. The privacy of all individuals involved
will be respected throughout the process.
---
## Advancement Process
1. **Nomination** by an eligible community member (Member or Higher) via a GitHub issue.
2. **Sponsorship** by two role holders at the **target level or higher** (within the specialty where applicable).
3. **Review** of activity and behavior (quality, reliability, collaboration, responsiveness).
4. **Decision** by lazy consensus of the relevant group (or **simple majority** if contested).
---
## Inactivity
A **Reviewer** or **Maintainer** role holder may be considered inactive if they
have not actively contributed or performed general project responsibilities for
**six (6) consecutive months**.
### Measurement Sources
- GitHub activity: Merged PRs, PR reviews, issue triage/comments.
- Participation in community calls or asynchronous design discussions.
### Triggering Process
1. **Detection**
- Activity is reviewed at least quarterly by Maintainers or via automation.
- Any Maintainer may propose an inactivity review for a role holder.
2. **Notification**
- A public issue is opened in a `community`/`governance` space (or email if sensitive).
- The individual is tagged/emailed and given **30 days** to respond.
3. **Grace Period**
- If the contributor indicates intent to return, no change is made.
- If there is no response within the grace period, proceed.
4. **Decision**
- Demotion is decided by **lazy consensus** of Maintainers, or **simple majority** if contested.
5. **Scope**
- Demotion via inactivity fully removes the role holder from the organization.
6. **Documentation**
- Update `OWNERS`, GitHub teams, and governance records.
- Former Members may be listed as **Emeritus**.
### Reinstatement
A contributor can be reinstated at their previous level via the standard
advancement process. Prior history is considered favorably.
---
## Emeritus Status
Emeritus status recognizes former Maintainers, Reviewers, or Members who have
made substantial and lasting contributions to the OAuth2-Proxy project but are
stepping down from active responsibilities.
Emeritus status is honorary and does not confer any formal responsibilities or
authority.
### Purpose
* Honor and recognize long-term contributions.
* Preserve institutional knowledge and mentorship potential.
* Encourage continued engagement with the community without requiring full role responsibilities.
---
## Cross-References
- Project governance and decision-making: see [GOVERNANCE.md](GOVERNANCE.md)
- Specialty ownership: [CODEOWNERS](./.github/CODEOWNERS) files per directory

170
GOVERNANCE.md Normal file
View File

@ -0,0 +1,170 @@
# OAuth2-Proxy Governance
This document defines the project governance for OAuth2-Proxy
## Overview
**OAuth2-Proxy** is a flexible, open-source tool that can act as either a
standalone reverse proxy or a middleware component integrated into existing
reverse proxy or load balancer setups. It provides a simple and secure way to
protect your web applications with OAuth2 / OIDC authentication. As a reverse
proxy, it intercepts requests to your application and redirects users to an
OAuth2 provider for authentication. As a middleware, it can be seamlessly
integrated into your existing infrastructure to handle authentication for
multiple applications.
OAuth2-Proxy supports a lot of OAuth2 as well as OIDC providers. Either through
a generic OIDC client or a specific implementation for Google, Microsoft Entra ID,
GitHub, login.gov and others. Through specialised provider implementations
oauth2-proxy can extract more details about the user like preferred usernames
and groups. Those details can then be forwarded as HTTP headers to your
upstream applications.
## Community Roles
- **Users**: Engineers and operators who deploy, configure, and maintain
OAuth2-Proxy in their environments. These are typically DevOps engineers,
SREs, or platform engineers who integrate OAuth2-Proxy with their
applications. End users who authenticate through OAuth2-Proxy typically do
not interact directly with OAuth2-Proxy
- **Contributors**: Anyone who makes contributions (code, docs, tests, reviews,
triage, discussions)
- **Reviewers / Maintainers**: Governance roles with defined responsibilities,
privileges, and promotion processes described in the [Contributor Ladder](CONTRIBUTOR_LADDER.md)
Maintainers are project leaders responsible for overall health, technical
direction, and release management.
---
## Maintainers
### Core Maintainers
Core Maintainers are a subset of Maintainers who have been with the project for
an extended period and have demonstrated consistent technical leadership and
commitment. They are responsible for major project decisions, including
governance changes and maintainer appointments.
### Expectations
Maintainers are expected to:
- Review pull requests, triage issues, and fix bugs in their areas of expertise
- Monitor community channels and help users and contributors
- Respond to time-sensitive security issues
- Follow the decision-making processes described in this document and in the
Contributor Ladder
If a maintainer cannot fulfill these duties, they should move to **Emeritus**
status. Maintainers may also be moved to Emeritus via the decision-making process.
### Adding or Removing Maintainers
- **Addition**: A candidate is nominated by an existing maintainer and elected
by a **simple majority** of current maintainers
- **Removal**: Removal requires a **simple majority** of current maintainers
- **Company voting**: Votes to nominate maintainers by contributors belonging
to the same employer count as **one** collective vote.
---
## Voting Eligibility
Voting rights vary by decision type:
| Decision Type | Eligible Voters |
|------------------------------------------------|----------------------------------------------|
| **Governance changes** | Core Maintainers |
| **Adding/removing Maintainers** | Core Maintainers |
| **Technical decisions within a specialty** | All Reviewers and Maintainers |
| **Project-wide technical direction** | All Maintainers |
| **Security incident decisions** | All Maintainers |
**Notes:**
- Company voting limits apply: maintainers/reviewers from the same declared
employer have **one** combined vote
- If maintainers/reviewers from the same declared employer cannot reach
consensus for their vote, that employer's vote is recorded as **abstain**
---
## Decision Making
OAuth2-Proxy strives for **consensus** via open discussion. When consensus
cannot be reached, any eligible voter may call a vote.
- **Simple Majority**: More than 50% of eligible voters in the group
- **Venues**: Votes may occur on GitHub, email, Slack, community meetings, or a
suitable voting service
- **Ballots**: "Agree/+1", "Disagree/-1", or "Abstain" (counts as no vote)
---
## Contributing Changes
The process of reviewing proposed changes differs depending on the size and
impact of the change.
### Minor Changes
A minor change is a bug fix, a smaller enhancement or a smaller addition to
existing features.
To propose a minor change, simply create an issue in our [Issue Tracker](https://github.com/oauth2-proxy/oauth2-proxy/issues) or directly create a pull request.
A maintainer will be responsible for ultimately approving the pull request. The
maintainer may do a deep review of the pull request or delegate to an expert in
the corresponding area.
If the change has a bigger impact it has to follow the process for larger
changes.
### Larger Changes
For larger changes all maintainers and contributors should have a chance of
reviewing the change. Therefore larger changes require an RFC to be created
through the [Issue Tracker](https://github.com/oauth2-proxy/oauth2-proxy/issues).
If there are any objections to the change they can in most cases be resolved
through discussions in the corresponding issue or pull request. If a resolution
can not be made it can be accepted if at least 2/3 of maintainers approve the
change.
---
## Lazy Consensus
OAuth2-Proxy uses [Lazy Consensus](http://en.osswiki.info/concepts/lazy_consensus) for most decisions.
- PRs and proposals should allow **at least eight (8) working days** for comments
- Other maintainers may request additional time when justified and commit to a
timely review
**Exclusions** (lazy consensus does **not** apply):
- Removal of maintainers
- Any substantive governance changes
---
## Updating Governance
Substantive changes to this document require a **simple majority** of Core Maintainers.
---
## Contributor Pathways & Specialties
Advancement pathways, responsibilities, privileges, and specialty areas are
defined in the [Contributor Ladder](CONTRIBUTOR_LADDER.md).
---
## Security
OAuth2-Proxy follows responsible disclosure practices. Security-impacting
issues should be reported via the documented security contact channels
(see `SECURITY.md` if present or repository Security tab). Security fixes may
be handled privately until a coordinated disclosure and release are ready.
---
## CNCF Alignment
OAuth2-Proxy governance aims for open, transparent, and vendor-neutral operation
consistent with CNCF expectations. The [Contributor Ladder](CONTRIBUTOR_LADDER.md)
provides clear pathways for community members to grow into leadership.

View File

@ -1,5 +0,0 @@
Joel Speed <joel@oauth2-proxy.dev> (@JoelSpeed)
Nick Meves <nick@oauth2-proxy.dev> (@NickMeves)
Braunson <braunson@oauth2-proxy.dev> (@braunsonm)
Jan Larwig <jan@oauth2-proxy.dev> (@tuunit)
Koen van Zuijlen <koen@oauth2-proxy.dev> (@kvanzuijlen)

33
MAINTAINERS.md Normal file
View File

@ -0,0 +1,33 @@
# Maintainers
The table below lists all current maintainers for the oauth2-proxy as defined
by our [project governance](GOVERNANCE.md).
| Name | GitHub Handle | Domains of reponsibility | Email Alias | Affiliation |
| ---------------- | ------------------------------------------------------ | ------------------------ | -------------------------- | ----------- |
| Joel Speed | [@JoelSpeed](https://github.com/joelspeed) | Governance, Core | joel@oauth2-proxy.dev | Red Hat |
| Jan Larwig | [@tuunit](https://github.com/tuunit) | Governance, Core | jan@oauth2-proxy.dev | IONOS Cloud |
| JJ Łakis | [@jjlakis](https://github.com/jjlakis) | Provider | jj@oauth2-proxy.dev | - |
| Koen van Zuijlen | [@kvanzuijlen](https://github.com/kvanzuijlen) | CI | koen@oauth2-proxy.dev | - |
| Pierluigi Lenoci | [@pierluigilenoci](https://github.com/pierluigilenoci) | Helm | pierluigi@oauth2-proxy.dev | SAP |
## Emeritus Maintainers
We would like to highlight that this project does have prior maintainers and
core contributors that, if they so wished, could (and should) be granted the
status of emeritus maintainers.
| Name | GitHub Handle |
| ------------- | ------------------------------------------------------ |
| Nick Meves | [@NickMeves](https://github.com/NickMeves) |
| Braunson | [@braunsonm](https://github.com/braunsonm) |
| Henry Jenkins | [@steakunderscore](https://github.com/steakunderscore) |
## Security Response Team and GitHub Organization Owners
The following maintainers are members of the security response team and owners
of the GitHub organization.
- Joel Speed
- Jan Larwig