Clarify Review Helper Checkout by ptr727 · Pull Request #817 · ptr727/ProjectTemplate

ptr727 · 2026-08-18T20:03:11Z

Summary

state where downstream agents run every scripts/pr_review.py command
clarify that the review helper is hub-hosted and never carried
regenerate the Copilot and Claude skill distributions

Why

PhotoCleaner PR #69 exposed that the numbered review loop could be read independently from its closing mechanics section. In a downstream repository, the unqualified command then points at a script that correctly does not exist there.

Verification

full OPERATIONS.md local verification chain
727 unit tests plus audit and write-guard self-tests
generated skill distribution consistency
repository and prose gates
JSON and spec validation
editorconfig-checker, ShellCheck, and PSScriptAnalyzer

…nups (#77) Release merge: brings two squashed PRs and one unnecessary back-merge commit from `develop` into `main`. ## Squashed PRs included - **#76 — Document `dotnet/nbgv@master` exception and drop redundant `secrets: inherit`.** - `.github/workflows/get-version-task.yml`: inline comment carves out `dotnet/nbgv@master` as the deliberate deviation from the AGENTS.md SHA-pinning rule (upstream tag stream is dormant, Dependabot would stall or attempt a downgrade if we pinned, upstream owner is Microsoft so retargeting risk is low). - `.github/workflows/build-nugetlibrary-task.yml`: dropped `secrets: inherit` from the `get-version` job call (same fix PR #74 applied to `build-pypilibrary-task.yml`). - **#78 — Forward-only develop with dual-target Dependabot + codegen.** The substantive change in this release: - **AGENTS.md "Branching Model"** explicitly codifies forward-only develop (no `main → develop` back-merges; develop squash-only ruleset blocks them) and the dual-target bot model with rationale. - **`.github/dependabot.yml`** duplicates every ecosystem entry per branch (six entries total) so Dependabot opens parallel PRs against both `main` and `develop` independently. Both branches stay current on dep versions without back-merges. - **`.github/workflows/run-codegen-pull-request-task.yml`** runs as a matrix over `main` and `develop`. Branch names `codegen-main` and `codegen-develop`; each opens a PR against its own base. - **`.github/workflows/merge-bot-pull-request.yml`** `merge-codegen` job uses strict head/base pairing and dispatches `--squash` (develop) vs `--merge` (main) per base, same `case` statement pattern as `merge-dependabot`. - **README.md "Template - Release Distribution Model: Push vs. Pull"** (new section) — documents the default push-on-merge model and the manual-release alternative for HACS / distro-vendored projects, referencing [homeassistant-purpleair](https://github.com/ptr727/homeassistant-purpleair) as the working example. - **README.md "Template - GitHub Setup"** rulesets section split into separate Develop (squash-only + `Require linear history`) and Main (merge-commit-only) rulesets with shared settings extracted. Repo-level Pull Requests block now correctly shows **both** `Allow merge commits` and `Allow squash merging` enabled (the prior wording suggested merge would be disabled, which contradicted the actual main ruleset). ## Unnecessary back-merge `5ce95cf` (acknowledged misstep) I opened this release with a `Merge remote-tracking branch 'origin/main' into develop` commit assuming the back-merge pattern was the standard cycle close. **It wasn't.** That model conflicts with AGENTS.md's squash-only develop rule (the push only succeeded via admin bypass). PR #78's AGENTS.md update now explicitly forbids future back-merges and routes both bots to update both branches independently — closing the gap that made this pattern feel necessary. The back-merge commit is left in place: reverting requires a destructive force-push to develop. Behavioral effect is a one-time gitHeight bump, which fixes the `--pre` channel ordering (develop's next dev publish is now unambiguously higher than main's last release). ## Operator action items (already completed) - `CODEGEN_APP_ID` / `CODEGEN_APP_PRIVATE_KEY` in both Actions and Dependabot secret stores. ✓ - `WORKFLOW_PAT` secret + PAT revoked. ✓ - `pypi` GitHub environment Deployment branch rule allows `main` and `develop`. ✓ ## Open follow-up (tracked separately, not in this release) PR #78 documented a limitation in the actor-check guardrail on `merge-codegen` / `merge-dependabot`: it stops the merge-bot from re-invoking `gh pr merge --auto` on a maintainer-triggered `synchronize`, but **does not** disable auto-merge that's already enabled. Once auto-merge is on a bot PR, maintainer commits will land. The honest workaround is documented (`gh pr merge --disable-auto <PR>` before pushing). The real safeguard — a `synchronize`-triggered job that disables auto-merge automatically when the actor isn't the bot — is a follow-up PR I'll open after this release lands. ## Notes - Merge method: **merge-commit** (per [AGENTS.md branching model](https://github.com/ptr727/ProjectTemplate/blob/develop/AGENTS.md#branching-model)). ## Test plan - [ ] CI passes on the merge commit. - [ ] `publish-release.yml` on main publishes `1.0.<N>.<B>` as the next stable release. - [ ] After release, `pip install ptr727-projecttemplate-library` resolves to the new stable; `pip install --pre ptr727-projecttemplate-library` resolves to the latest develop dev (assuming develop's gitHeight exceeds main's, which the back-merge ensures). - [ ] Next Dependabot scheduled run opens **two** PRs per ecosystem (one against main, one against develop). - [ ] Next codegen weekly run opens **two** PRs (`codegen-main` against main, `codegen-develop` against develop). - [ ] Each bot PR auto-merges via the merge-bot with the correct method (`--squash` for develop, `--merge` for main).

…rules-docs alignment (#80) Release merge: brings two squashed PRs from `develop` into `main`. ## Squashed PRs included - **#79 — Disable auto-merge on maintainer push to bot PR.** Started narrow (a `synchronize`-triggered job that calls `gh pr merge --disable-auto` when a maintainer pushes to a bot PR, closing the gap PR #78 documented but didn't fix) and grew to cover repo-wide SHA pinning of every action after the maintainer corrected my reading of AGENTS.md's first-party-actions clause. ### What landed - **New `disable-auto-merge-on-maintainer-push` job** in `.github/workflows/merge-bot-pull-request.yml`. Fires on `pull_request.synchronize` events against bot-authored PRs (Dependabot or codegen) when the event actor isn't the same bot — calls `gh pr merge --disable-auto`. App-token-driven (Dependabot PRs run with restricted secrets regardless of event actor). - **`merge-dependabot` and `merge-codegen` restricted to `opened`/`reopened`** so auto-merge is enabled exactly once per PR; skipping `synchronize` is what keeps the disable safeguard sticky against bot rebases. - **`concurrency.cancel-in-progress: false`** in `merge-bot-pull-request.yml` so the three-job model runs events to completion in arrival order. - **Every action SHA-pinned** across all workflows: `actions/*` (checkout, setup-dotnet, create-github-app-token, upload-artifact, download-artifact), `docker/*` (setup-qemu-action, setup-buildx-action, login-action, build-push-action), and `RubbaBoy/BYOB`. `dotnet/nbgv@master` is the only documented exception. - **AGENTS.md "Workflow YAML Conventions"** tightened: every action must be SHA-pinned (the prior "first-party `actions/*` encouraged but not required" softening is gone). `# vX` major-only comment allowed when upstream's floating major tag doesn't correspond to a specific patch/minor release SHA. Concurrency convention gains a documented exception for `merge-bot-pull-request.yml`. - **AGENTS.md "Branching Model"** + **README "Template - GitHub Setup"** updated for the new disable job and the auto-merge condition list. - **#81 — Drop "branches up to date" rule from main ruleset (incompatible with forward-only).** Resolved the root cause behind PR #80 being initially blocked. GitHub's "Require branches to be up to date before merging" is a graph-based check (it asks whether main's tip merge commit is reachable from develop) that's fundamentally incompatible with the forward-only develop model PR #78 codified. Historical back-merges had been quietly compensating for this; PR #78 forbade them but left the README's documented "shared settings" ruleset block contradictorily listing the rule. - **README "Rules / Rulesets"**: moved `Require branches to be up to date before merging` out of "Shared settings" into the Develop-only ruleset entry (where it's standard hygiene). Added explicit "intentionally OFF" callout in the Main ruleset entry with the full rationale. - **AGENTS.md "Branching Model"**: new bullet codifying *why* the main ruleset omits this rule, framed purely in graph-reachability terms. ## Operator action already completed - `Require branches to be up to date before merging` unticked on Settings → Rulesets → Main. ✓ Verified via API. ## Notes - Merge method: **merge-commit** (per [AGENTS.md branching model](https://github.com/ptr727/ProjectTemplate/blob/develop/AGENTS.md#branching-model)). - **No rebase required.** With the ruleset rule now disabled, GitHub no longer enforces graph-reachability of main's tip from develop, so the merge proceeds cleanly without admin bypass or back-merge. ## Test plan - [ ] CI passes on the merge commit. - [ ] `publish-release.yml` on main produces the next stable release. - [ ] Next bot PR (Dependabot or codegen) opens with auto-merge enabled exactly once. A maintainer push to the bot's branch disables auto-merge; re-enable manually to land the maintainer's edits. - [ ] No floating-tag actions remain anywhere in `.github/workflows/` except `dotnet/nbgv@master`. - [ ] Future develop → main releases land without admin bypass.

## Summary - Closes#82 — drop strict "Require branches to be up to date before merging" from the `develop` ruleset (already applied on the live ruleset id 15886282). With strict on, two bot PRs against `develop` landing within the same window left the second OPEN forever: the first merge flipped it to `mergeStateStatus: BEHIND`, GitHub's auto-merge will not fire while strict is on, and the merge-bot only enables auto-merge on `opened`/`reopened`. - Closes#83 — fix the GitHub Pre-Release shield with `&filter=*-g*` (NBGV pre-release tags carry a `-g<sha>` suffix, stable tags don't); drop the NuGet Pre-Release badge because shields.io's `vpre` endpoint accepts no filter parameter and silently returns the latest stable whenever one exists. - AGENTS.md "Branching Model" + README.md "Rules / Rulesets" updated in lockstep — both rulesets now document distinct reasons for omitting the strict flag. ## Test plan - [ ] Visual: rendered README badge row shows three pre-release-aware badges (GitHub Release, GitHub Pre-Release, NuGet Release) — `NuGet Pre-Release` is gone. - [ ] Shield URL spot-check: `https://img.shields.io/github/v/release/<owner>/<repo>?include_prereleases&filter=*-g*` renders an NBGV pre-release tag, not the latest stable. - [ ] `gh api repos/ptr727/ProjectTemplate/rulesets/15886282 | jq '.rules[] | select(.type=="required_status_checks")'` shows `strict_required_status_checks_policy: false` (already verified). - [ ] Next pair of overlapping Dependabot/codegen PRs against `develop` both auto-merge without one stalling in `BEHIND`.