diff --git a/CHANGELOG.md b/CHANGELOG.md index 57803c00..e6f03b74 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ## [Unreleased] +### Changed + +- `docs/adopt.md`'s NCode Review steps, 0.3 and section 5 with 5.1, link NCode Review's own runbook, [Set Up NCode Review, End to End](https://github.com/NCodeGroup/code-review/blob/main/docs/setup.md), at its once-per-organization, once-per-repository and troubleshooting sections, instead of NCodeGroup/code-review's README sections "Using it" and "Opting a repository in", so NCode Review's setup has one procedure ([#472](https://github.com/NCodeGroup/project-template/issues/472)). +- `USAGE.md`'s NCode Review paragraph sends an existing project to `.\.template\Update-Project.ps1 -Data @{ code_review = $true }`, `docs/adopt.md` section 5 and NCode Review's runbook, and names the NCode Review Approver's installation and `Enable-CodeReview.ps1`'s `-ApproverPrivateKeyPath`, which it left out, so a maintainer who follows it sets up the approval too ([#472](https://github.com/NCodeGroup/project-template/issues/472)). + ## [0.111.3] - 2026-11-21 ### Fixed diff --git a/USAGE.md b/USAGE.md index 217e21a9..7ea97c99 100644 --- a/USAGE.md +++ b/USAGE.md @@ -191,7 +191,7 @@ Adopt one from this repository's clone. See [Adopt an existing repository](READM On GitHub, `Adopt-Project.ps1` ends by printing the command that protects the repository's default branch so changes reach it only through pull requests (`tools\Set-RepositoryBaseline.ps1`, [Protect the Default Branch](README.md#protect-the-default-branch)). On GitLab, it prints the command that protects the project (`tools\Set-GitLabBaseline.ps1`), with its "All threads must be resolved" and "Pipelines must succeed" merge checks, "Squash commits when merging" set to "Do not allow" and no one allowed to push to the default branch, to run signed in to `glab` as a Maintainer of the project. `New-Project.ps1 -CreateRemote` runs either for you. Run the printed command once, from this clone, signed in to `gh` as an administrator of the repository on GitHub. -To have the NCode Review bot review a GitHub project's pull requests, answer yes to the `code_review` question when you create it. A project that already exists copies `.github/workflows/code-review.yml` from a new project, or from NCodeGroup/Identity, and pins `NCodeGroup/code-review` to a release's full commit SHA, with its tag in a comment. Then, once per repository, run `tools\Enable-CodeReview.ps1 -Repo ` from a clone of `NCodeGroup/code-review`: it creates the `code-review` environment and gives the repository the organization's secrets. Without that step, the review job fails. +To have the NCode Review bot review a GitHub project's pull requests, and its NCode Review Approver approve them, answer yes to the `code_review` question when you create it; a project that already exists gets `.github/workflows/code-review.yml` from `.\.template\Update-Project.ps1 -Data @{ code_review = $true }`, run in the project. Then set the repository up once, as [docs/adopt.md](docs/adopt.md#5-ncode-review) section 5 says, after NCode Review's runbook, [Set Up NCode Review, End to End](https://github.com/NCodeGroup/code-review/blob/main/docs/setup.md): add the repository to both apps' installations, NCode Review and NCode Review Approver, and run `tools\Enable-CodeReview.ps1 -Repo -ApproverPrivateKeyPath ` from a clone of `NCodeGroup/code-review`, which creates the `code-review` environment, gives the repository the organization's secrets and stores the approver's key there. Without that step, the review job fails. To get the commands and skills in every repository, run: diff --git a/docs/adopt.md b/docs/adopt.md index 6055fc8b..9e8614e0 100644 --- a/docs/adopt.md +++ b/docs/adopt.md @@ -63,10 +63,10 @@ Do these once per organization, and once per maintainer's PC for 0.1. - **Applies to:** GitHub, with NCode Review - **Who:** an organization owner, with `admin:org`. -- **Where:** NCodeGroup/code-review's README. -- **Do:** Create and install the two apps, NCode Review and NCode Review Approver, set up Anthropic, and store the organization secrets `NCODE_REVIEW_APP_PRIVATE_KEY` and `AWS_BEARER_TOKEN_BEDROCK` with its `tools/Enable-CodeReview.ps1`, as `https://github.com/NCodeGroup/code-review#using-it` says. Its end-to-end runbook is NCodeGroup/code-review#237. This page doesn't repeat it. +- **Where:** NCodeGroup/code-review's runbook, [Set Up NCode Review, End to End](https://github.com/NCodeGroup/code-review/blob/main/docs/setup.md). +- **Do:** Follow the runbook's [1. Once per Organization](https://github.com/NCodeGroup/code-review/blob/main/docs/setup.md#1-once-per-organization), 1.1 to 1.5: give `gh` the `admin:org` scope, create and install the two apps, NCode Review and NCode Review Approver, set up Anthropic, and store the organization secrets `NCODE_REVIEW_APP_PRIVATE_KEY` and `AWS_BEARER_TOKEN_BEDROCK` with NCodeGroup/code-review's `tools/Enable-CodeReview.ps1`. This page doesn't repeat them. - **Check:** `gh secret list --org ` lists both secrets. -- **Goes wrong:** see code-review's runbook (NCodeGroup/code-review#237) for its own troubleshooting. +- **Goes wrong:** see the runbook's [5. Troubleshooting](https://github.com/NCodeGroup/code-review/blob/main/docs/setup.md#5-troubleshooting). ## 1. Create or Adopt @@ -270,16 +270,16 @@ This section is for a .NET library on GitHub with the template's `publish.yml`, ## 5. NCode Review -This section is for a GitHub project with NCode Review, after [0.3](#03-ncode-reviews-organization-setup). `https://github.com/NCodeGroup/code-review#opting-a-repository-in` and NCodeGroup/code-review#237 give the per-repository steps in full. +This section is for a GitHub project with NCode Review, after [0.3](#03-ncode-reviews-organization-setup). NCode Review's runbook gives the per-repository steps in full, in [2. Once per Repository](https://github.com/NCodeGroup/code-review/blob/main/docs/setup.md#2-once-per-repository); 5.1 to 5.3 summarize them, in the same order. ### 5.1 Set Up the Repository - **Applies to:** GitHub, with NCode Review - **Who:** an organization owner (`admin:org`). - **Where:** each app's installation settings (Organization settings > GitHub Apps > Configure > Repository access), and an up-to-date clone of NCodeGroup/code-review (run `git pull` first). -- **Do:** Add the repository to both apps' installations, NCode Review and NCode Review Approver. Run `.\tools\Enable-CodeReview.ps1 -Repo -ApproverPrivateKeyPath `. It creates the `code-review` environment (default branch only), gives the repository the organization secrets, and stores `NCODE_REVIEW_APPROVER_PRIVATE_KEY` in that environment. Then delete the `.pem` (see [7.3](#73-rotate-a-key)). Make sure the default branch has `.github/workflows/code-review.yml`, from the `code_review` answer (see [1.1](#11-a-new-project) and [1.2](#12-an-existing-repository)) or from `.\.template\Update-Project.ps1 -Data @{ code_review = $true }` in the project. It pins NCodeGroup/code-review v1.5.0 or later by full commit SHA, and its review job passes `approve: true` and `approver-private-key: ${{ secrets.NCODE_REVIEW_APPROVER_PRIVATE_KEY }}`. `.template\Update-Project.ps1` says what an older file lacks. +- **Do:** As the runbook's [2.1](https://github.com/NCodeGroup/code-review/blob/main/docs/setup.md#21-add-the-repository-to-both-apps-installations), [2.2](https://github.com/NCodeGroup/code-review/blob/main/docs/setup.md#22-store-the-approvers-key) and [2.3](https://github.com/NCodeGroup/code-review/blob/main/docs/setup.md#23-pass-the-approval-inputs-in-code-reviewyml) say, add the repository to both apps' installations, NCode Review and NCode Review Approver. Run `.\tools\Enable-CodeReview.ps1 -Repo -ApproverPrivateKeyPath `. It creates the `code-review` environment (default branch only), gives the repository the organization secrets, and stores `NCODE_REVIEW_APPROVER_PRIVATE_KEY` in that environment. Then delete the `.pem` (see [7.3](#73-rotate-a-key)). Make sure the default branch has `.github/workflows/code-review.yml`, from the `code_review` answer (see [1.1](#11-a-new-project) and [1.2](#12-an-existing-repository)) or from `.\.template\Update-Project.ps1 -Data @{ code_review = $true }` in the project. It pins NCodeGroup/code-review v1.5.0 or later by full commit SHA, and its review job passes `approve: true` and `approver-private-key: ${{ secrets.NCODE_REVIEW_APPROVER_PRIVATE_KEY }}`. `.template\Update-Project.ps1` says what an older file lacks. - **Check:** `gh secret list --env code-review --repo /` lists `NCODE_REVIEW_APPROVER_PRIVATE_KEY`. -- **Goes wrong:** a stale clone's script doesn't know `-ApproverPrivateKeyPath`; `gh`'s token can't list an installation's repositories, so the script warns and goes on, and you add the repository on the app's page; a public repository needs the event policy (see [0.2](#02-the-organizations-actions-policy) or [2.1](#21-run-the-baseline)) or GitHub blocks the review. +- **Goes wrong:** a stale clone's script doesn't know `-ApproverPrivateKeyPath`; `gh`'s token can't list an installation's repositories, so the script warns and goes on, and you add the repository on the app's page; a public repository needs the event policy (see [0.2](#02-the-organizations-actions-policy) or [2.1](#21-run-the-baseline)) or GitHub blocks the review; the runbook's [5. Troubleshooting](https://github.com/NCodeGroup/code-review/blob/main/docs/setup.md#5-troubleshooting) has the rest. ### 5.2 Require the Approval