From 4a459396d413ef632f58fa07a1516be4a63d561a Mon Sep 17 00:00:00 2001 From: ZouR-Ma <2605315944@qq.com> Date: Thu, 15 Oct 2026 16:03:56 +0800 Subject: [PATCH] chore: define fixed internal pull request reviews --- .github/CODEOWNERS | 4 ++ CONTRIBUTING.md | 24 +++++++++ docs/repository-review.md | 104 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 132 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 docs/repository-review.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..2ce6fa01 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,4 @@ +# Fixed internal review pool for every repository path, including this file. +# Keep the enforced approval roster aligned with these four owners. +# CODEOWNERS routes reviews; GitHub rules enforce the approval count. +* @liuedcson @MelodyVAR @Uking-xxx @ZouR-Ma diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2bbafca1..77bebfaf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,30 @@ This guide exists to save both sides time. +## Contribution access and required reviews + +StepCode accepts pull requests from invited collaborators. Keep pull request +creation set to **Collaborators only**. Invited external developers receive +**Write** access to this repository and may work in a fork or a development +branch, then open a pull request targeting `main`. + +The four maintainers listed in [.github/CODEOWNERS](.github/CODEOWNERS) form the +fixed internal review pool for all repository paths. Each pull request requires +approval from **at least one member of that pool**, excluding the +pull request author. External collaborators' approvals do not count toward this +internal requirement. Maintainer-authored pull requests follow the same rule. + +Before merging, the required CI checks must pass, review conversations must be +resolved, and approvals must cover the current changes. Code changes after an +approval require renewed review. An internal maintainer performs the merge; +contributors must not push directly to `main`. + +`CODEOWNERS` requests reviews but does not enforce required owner approval or +restrict who can merge. These requirements must also be enabled in GitHub's +repository settings. See the [repository review configuration](docs/repository-review.md) +for setup and verification; adding these files alone does not activate those +settings. + ## Philosophy First things first: **StepCode's core is minimal**. diff --git a/docs/repository-review.md b/docs/repository-review.md new file mode 100644 index 00000000..28aeadb0 --- /dev/null +++ b/docs/repository-review.md @@ -0,0 +1,104 @@ +# Repository access and review configuration + +This guide describes the GitHub settings needed to enforce the +[contribution review policy](../CONTRIBUTING.md#contribution-access-and-required-reviews): +at least one approval from the fixed internal review pool, passing CI, and merging +by an internal maintainer. Repository files do not activate these settings. + +## Contribution access and reviewer membership + +1. In **Settings > General > Features > Pull requests**, keep **Creation allowed + by: Collaborators only**. +2. Grant invited external developers **Write**, without Maintain, Admin, or any + ruleset bypass role. Read and Triage do not qualify for this PR creation policy + in an organization-owned repository. Write is repository write access, so the + branch restrictions below are also required. +3. Use the four individual maintainers in [CODEOWNERS](../.github/CODEOWNERS) as + the review pool for every repository path. Each owner must retain Write access + or higher. Organization membership and an organization team are not required. +4. Keep `CODEOWNERS` and the four-account merge allowlist synchronized when the + maintainer roster changes. Maintain or Admin access alone does not place a + person in the fixed review or merge pool. + +External Write collaborators can submit reviews, including Approve. Their +approvals do not satisfy the required Code Owner review. The PR author cannot +approve their own PR, including when the author is one of the four maintainers. + +## Required reviews and checks + +Merge `CODEOWNERS` into `main` first, then activate the review ruleset below. +Until it exists on the base branch, requiring a Code Owner review cannot enforce +the fixed reviewer roster. Prepare the ruleset as **Disabled** while this +prerequisite is pending; do not describe the one-internal-approval gate as active. + +In **Settings > Rulesets**, configure a branch ruleset named +`main-review-requirements` targeting `main`. Keep any existing protections enabled. + +| Setting | Required configuration | +| --- | --- | +| Enforcement status | Active only after `CODEOWNERS` is present on `main` and its owners are valid. | +| Bypass list | Empty; internal maintainers must also satisfy reviews and CI. | +| Require a pull request before merging | Enabled. | +| Required approvals | 1. | +| Require review from Code Owners | Enabled for every path through the catch-all `CODEOWNERS` rule. | +| Dismiss stale approvals | Enabled when new commits change the PR diff. | +| Require approval of the most recent reviewable push | Enabled. | +| Require conversation resolution | Enabled. | +| Require status checks to pass | Require the build/check/test job and the commit attribution check. | +| Restrict deletions / Block force pushes | Enabled. | + +Select the actual check names emitted by [CI](../.github/workflows/ci.yml) and +[Commit attribution](../.github/workflows/commit-attribution.yml), normally +`build-check-test` and `Check commit attribution`. Pin each required check to its +GitHub Actions source where available. Do not require the scheduled `npm audit` +job, which does not run on pull requests. + +The owner-review requirement is essential: one generic approval can come from an +external Write collaborator. A `CODEOWNERS` line naming four people requires any +one eligible owner to approve, not all four. This setup does not enforce two +internal approvals; that would require a team-specific rule or a separate trusted +approval gate. + +## Restrict who can merge + +Use a separate **Active** branch ruleset named `main-internal-merges`, also +targeting `main`: + +- Enable **Restrict updates**, **Restrict deletions**, and **Block force pushes**. +- Add only the four individual accounts listed in `CODEOWNERS` to this ruleset's + bypass list, each using **For pull requests only**. +- Do not add the Write, Maintain, or Admin role, other collaborators, or a broad team. + +This bypass permits the four maintainers to update `main` through a PR under this +rule only. It must not be added to `main-review-requirements`: the separate review +ruleset still requires owner approval, resolved conversations, and passing CI. +External Write collaborators can propose changes but cannot merge them into `main`. +After all requirements pass, the owner who approved the PR may also merge it. + +Apply equivalent protections to any other maintained branch before accepting +external contributions to that branch. + +## Verification before onboarding + +Inspect the effective rules for `main`, including organization-level rules and +bypasses, then verify the following on a test PR without merging it: + +| Scenario | Expected result | +| --- | --- | +| No internal owner approval, even with external approvals | Merge blocked. | +| Approval only from the PR author | Does not satisfy review requirements. | +| One eligible internal approval, failed or pending required CI | Merge blocked. | +| New code pushed after approval | Renewed review required. | +| One eligible internal approval, passing CI, resolved conversations | One of the four maintainers can merge; other collaborators cannot. | + +Check review routing and required owner approval for a root file, a nested source +file, and a `.github/` file. Confirm direct pushes to `main` are denied, including +for the four maintainers. Local changes and a PR's head copy of `CODEOWNERS` do +not configure the base branch. + +## GitHub references + +- [PR creation permissions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-pull-requests) +- [CODEOWNERS behavior](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) +- [Ruleset review and update rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets) +- [Ruleset targets and bypass permissions](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository)