From 68d9e4fba6d71a18a96a21b52b109a160bd03fff Mon Sep 17 00:00:00 2001 From: fly1d Date: Fri, 14 Aug 2026 18:15:14 +0800 Subject: [PATCH] docs: support solo-maintainer governance --- .github/pull_request_template.md | 9 +++++ CONTRIBUTING.md | 31 ++++++++++++------ docs/QUALITY_GATES.md | 56 +++++++++++++++++++++++++++----- 3 files changed, 78 insertions(+), 18 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 905feff..4051599 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -15,6 +15,15 @@ Describe the user-visible or operational outcome. - Failure mode: - Rollback plan: +## Review decision + +- Mode: team / solo-maintainer +- Independent reviewer(s), if required: +- Final material push (medium-risk solo mode): not applicable / YYYY-MM-DD HH:MM UTC +- Earliest merge (medium-risk solo mode): not applicable / YYYY-MM-DD HH:MM UTC +- High-risk production status: not applicable / approved / experimental and prohibited +- Owner decision (solo mode): hold / merge + ## Release notes State `none` or provide a concise changelog entry. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d1c28c..5d389b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,26 +6,37 @@ 2. Keep the pull request focused on one behavior or decision. 3. Add or update tests for observable behavior. 4. Run `make check` locally. -5. Complete the pull request risk assessment and request review. -6. Merge only after required checks and approvals pass. +5. Complete the pull request risk assessment and select team or solo-maintainer review mode. +6. Record the required approval or owner decision. +7. Merge only after the applicable checks, review evidence, and waiting period pass. Direct pushes to `main` are not part of the normal workflow. Emergency fixes still use a pull -request, one reviewer, and the smoke suite; any deferred evidence is added within one business -day. +request and the smoke suite. A solo maintainer may waive only the cooling period for an active +incident, must explain why in the owner decision, and adds any deferred evidence within one +business day. A cooling-period waiver does not waive a high-risk production review. ## Review expectations -Reviewers focus on behavior, failure modes, security boundaries, compatibility, operability, -and tests. Formatting and routine static checks belong to automation. +Reviewers and solo-maintainer self-review focus on behavior, failure modes, security boundaries, +compatibility, operability, and tests. Formatting and routine static checks belong to +automation. -- Low risk: one approval and fast CI. -- Medium risk: one domain-owner approval, rollback notes, and relevant integration evidence. -- High risk: two approvals, including a security or data owner, migration rehearsal, and an - explicit rollback plan. +- Team mode requires one approval for low and medium risk and two relevant approvals for high + risk. +- Solo-maintainer mode allows low-risk merge after recorded owner review and passing CI. +- Solo-maintainer medium-risk work also requires rollback evidence and 24 hours after the final + material push. +- Solo-maintainer high-risk work requires independent external review before production release. + Without it, merge is allowed only under the experimental restrictions in + `docs/QUALITY_GATES.md`. High-risk examples include authorization, destructive tools, memory retention, secrets, database migrations, public schemas, and prompt promotion logic. +An AI review or a second account controlled by the author is not an independent approval. An +external reviewer does not need to be an employee, but must have relevant expertise and no +authorship conflict for the reviewed change. + ## Compatibility Public contracts are versioned. Removing a field, narrowing accepted input, or changing diff --git a/docs/QUALITY_GATES.md b/docs/QUALITY_GATES.md index 39a9e2b..75701ec 100644 --- a/docs/QUALITY_GATES.md +++ b/docs/QUALITY_GATES.md @@ -18,11 +18,46 @@ retries must not turn an unreliable result green. ## Change risk -| Risk | Examples | Review requirement | -| --- | --- | --- | -| Low | documentation, internal refactor, additive tests | one approval | -| Medium | new endpoint, adapter, retry behavior, dependency | owner approval and rollback note | -| High | auth, tool execution, memory deletion, migration, public schema removal | two approvals and rehearsal evidence | +The repository uses team mode when at least two trusted maintainers can review and merge. It uses +solo-maintainer mode when only one person has that authority. A solo maintainer must not use an +alternate account to manufacture independence. Automated or AI-assisted review is useful +evidence, but it is not an independent human approval. + +| Risk | Examples | Team mode | Solo-maintainer mode | +| --- | --- | --- | --- | +| Low | documentation, internal refactor, additive tests | one approval and fast CI | recorded owner decision and fast CI | +| Medium | new endpoint, adapter, retry behavior, dependency | domain-owner approval, rollback note, and relevant evidence | recorded owner decision, rollback note, relevant evidence, and a 24-hour cooling period | +| High | auth, tool execution, memory deletion, migration, public schema removal | two approvals, including the relevant security or data owner, plus rehearsal evidence | independent external domain review before production release, plus rehearsal evidence and an explicit rollback plan | + +The solo-maintainer cooling period starts after the final material push. A change to behavior, +dependencies, permissions, deployment configuration, public contracts, or risk analysis resets +the period; typo-only or review-metadata updates do not. The pull request records the final +material push time and earliest merge time. + +For a high-risk change, an external reviewer can be a trusted open-source maintainer, contractor, +consultant, or customer security/data owner. If no external reviewer is available, the solo +maintainer may merge only when all of the following are true: + +- the capability is not deployed to or designated for production and is disabled by default + where that control is applicable; +- the pull request and user documentation label it experimental and not approved for production; +- rehearsals and rollback evidence pass in an isolated environment; +- the owner decision names the restriction and the evidence required to remove it. + +Merging under that exception does not authorize production deployment. Removing the restriction +is itself a high-risk change and requires the independent external review. + +## Owner decision record + +In solo-maintainer mode, approval is an explicit risk decision rather than a GitHub approval on +the author's own pull request. The pull request must state: + +- the risk level and why it is correctly classified; +- the checks, smoke tests, and review performed; +- the failure mode and rollback plan; +- the final material push and earliest merge time for medium-risk work; +- any external review or production restriction required for high-risk work; +- a final `merge` or `hold` decision from the repository owner. ## Smoke test contract @@ -45,7 +80,6 @@ newer one. Major tool upgrades are reviewed separately from routine maintenance. Configure a GitHub ruleset for `main` with: - pull requests required; -- at least one approval; - stale approvals dismissed after new code is pushed; - conversation resolution required; - `fast-gate` and `container-build` required; @@ -53,5 +87,11 @@ Configure a GitHub ruleset for `main` with: - force pushes and deletion blocked; - administrators subject to the same rules. -Repository rules must be configured after the GitHub remote and owner are known; workflow files -alone cannot enforce approvals. +In team mode, require at least one approving review in GitHub and enforce the additional +high-risk approval through the pull request policy. In solo-maintainer mode, set required +approvals to zero because GitHub does not allow an author to approve their own pull request; +enforce the owner decision record, cooling period, and external production review through the +pull request. Switch the ruleset to team mode as soon as a second trusted maintainer accepts +review responsibility. + +Workflow files alone cannot enforce human approvals, cooling periods, or production restrictions.