From b7add3d11dc4ba8784ef53e403322aaaee97394b Mon Sep 17 00:00:00 2001 From: Will-thom <116388885+Will-thom@users.noreply.github.com> Date: Sun, 31 May 2026 01:43:54 -0300 Subject: [PATCH] docs: require code owner review gate --- MAINTAINERS.md | 6 +++++- docs/ci.md | 2 +- docs/oss-guardrails.md | 8 ++++---- docs/permissions.md | 20 ++++++++++++-------- 4 files changed, 22 insertions(+), 14 deletions(-) diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 8714c59..9fc95e2 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -25,14 +25,18 @@ External contributors are welcome to open issues and pull requests. A maintainer The default branch is `main`. It should stay protected and use the `All CI checks` status as the required CI gate. +Pull requests should require at least one approving review and review from the repository code owner before merge. + GitHub repository permissions should keep merge rights limited to users with write, maintain, or admin access. External contributors can propose changes through issues and pull requests, but they should not have merge access. Label policy is documented in [docs/labels.md](docs/labels.md). Pull requests should not be merged while unlabeled when they affect release notes, roadmap order, or contributor-facing backlog state. +While `@Will-thom` is the only maintainer and only repository-wide code owner, the repository may keep a founder bypass for required pull request reviews to avoid deadlocking founder-authored maintenance PRs. The bypass should be treated as an operational escape hatch, not the normal review path. + ## Maintainer Path Additional maintainers may be invited after sustained, high-quality contributions and review participation. Maintainer access should stay intentionally small while the project is young. -Before inviting additional maintainers with write access, update branch protection to require at least one pull request review. Consider requiring code owner review for changes to production code, GitHub workflows, release automation, JSON output contracts, and CLI user-facing behavior. +After adding another trusted maintainer or code owner, remove any founder review bypass and keep required code owner review as the normal merge gate. diff --git a/docs/ci.md b/docs/ci.md index 7e69b93..38c2141 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -118,4 +118,4 @@ Only users with maintainer-level repository permissions should merge pull reques Delete pull request head branches after merge so the repository does not accumulate stale contribution branches. -Before adding more maintainers, require at least one pull request review and consider requiring code owner review for changes that touch production code, workflows, release automation, or public output contracts. +The default branch should require at least one approving pull request review and a code owner review. While `@Will-thom` is the only maintainer and code owner, a documented founder bypass may remain enabled to avoid deadlocking founder-authored maintenance PRs. diff --git a/docs/oss-guardrails.md b/docs/oss-guardrails.md index 09717d3..1c9ab41 100644 --- a/docs/oss-guardrails.md +++ b/docs/oss-guardrails.md @@ -14,6 +14,8 @@ The project follows a conservative OSS posture inspired by mature Maven ecosyste - `main` is the default branch. - `main` requires the `All CI checks` status before merge. +- `main` requires at least one approving pull request review before merge. +- `main` requires code owner review before merge. - `main` blocks force pushes and branch deletion. - Pull request head branches are deleted after merge. - Conversation resolution is required before merge. @@ -54,8 +56,8 @@ Stage 3 provider adapters must be additive. Provider failures should not erase l Before adding maintainers or collaborators with write access, maintainers should: -- require at least one pull request review; -- consider requiring code owner review for production code and workflow changes; +- confirm required pull request review and code owner review are still enabled; +- remove any founder-only review bypass once another trusted maintainer or code owner can review founder-authored PRs; - confirm only maintainers can merge; - confirm `All CI checks` remains the required protected status; - confirm no unexpected secrets, variables, webhooks, environments, deployments, or Pages configuration exists. @@ -72,8 +74,6 @@ Before adding maintainers or collaborators with write access, maintainers should These controls are intentionally deferred until they fit the maintainer model: -- required pull request review while the project has only one maintainer; -- code owner review requirement; - GitHub Actions allowlist or SHA pinning; - signed tags; - SBOM generation and SBOM attestations. diff --git a/docs/permissions.md b/docs/permissions.md index edab243..88d9ff6 100644 --- a/docs/permissions.md +++ b/docs/permissions.md @@ -23,6 +23,8 @@ The public repository must keep `main` protected before accepting outside contri Required public-mode controls: - Require the `All CI checks` status before merge. +- Require at least one approving pull request review before merge. +- Require review from the repository code owner before merge. - Enforce the rule for administrators. - Require conversation resolution before merge. - Disable force pushes. @@ -31,12 +33,12 @@ Required public-mode controls: - Keep merge rights limited to users with write, maintain, or admin access. - Keep `@Will-thom` as the repository-wide code owner through `.github/CODEOWNERS`. -Before adding additional maintainers or collaborators with write access: +Founder deadlock prevention: -- require at least one pull request review before merge; -- consider requiring code owner review for production code, workflows, release automation, and output contracts; -- keep direct pushes to `main` disabled through branch protection; -- document any intentional exception in `MAINTAINERS.md`. +- `@Will-thom` may be configured as a pull request review bypass actor while the project has only one maintainer. +- This bypass exists to prevent the founder from being unable to merge founder-authored maintenance PRs. +- It should be used only when CI is green, conversations are resolved, labels are correct, and the change is intentionally scoped. +- Remove the bypass after at least one additional trusted maintainer or code owner can review founder-authored PRs. ## GitHub Actions Permissions @@ -84,6 +86,8 @@ Before actively inviting OSS contributors: 1. Validate branch protection for `main`. 2. Confirm `All CI checks` is the required status gate. 3. Confirm `CODEOWNERS` still routes ownership to `@Will-thom`. -4. Confirm secret scanning, push protection, and Dependabot security updates are still enabled. -5. Confirm no unintended collaborators, secrets, variables, webhooks, environments, deployments, releases, or pages were added. -6. Re-run CI and Security on `main`. +4. Confirm pull request reviews and code owner review are required. +5. Confirm any founder bypass is still intentional and documented. +6. Confirm secret scanning, push protection, and Dependabot security updates are still enabled. +7. Confirm no unintended collaborators, secrets, variables, webhooks, environments, deployments, releases, or pages were added. +8. Re-run CI and Security on `main`.