Drop "branches up to date" rule from main ruleset (incompatible with forward-only) - #81
Merged
Merged
Conversation
…forward-only) PR #80 (the develop -> main release) failed `gh pr merge --merge` with "the head branch is not up to date with the base branch". That's the ruleset's "Require branches to be up to date before merging" check failing — and it's a fundamental incompatibility with the forward-only develop model PR #78 codified. The check is graph-based: it asks "is main's tip commit reachable from develop?", not "does develop have main's content?". After any develop -> main release, main has a new merge commit (e.g. fb10a16 from PR #77) whose first-parent walk isn't in develop's history, so develop is always "behind" in the graph sense even though it's strictly ahead in content. Historical back-merge commits (ffb9e64, 5ce95cf) had been quietly compensating for this — they put main's release-merge commit into develop's history via the merge commit's second parent. PR #78 forbade back-merges on develop, but the README rulesets section still listed "Require branches to be up to date" as a shared setting, leaving the contradiction hidden until the first release without a back-merge tried to land. This PR resolves the contradiction: - README.md "Rules / Rulesets": move "Require branches to be up to date before merging" out of "Shared settings" and into the Develop-only ruleset (where it's standard hygiene for feature -> develop merges). Add explicit "intentionally OFF" callout in the Main ruleset entry with the rationale, pointing at AGENTS.md. - AGENTS.md "Branching Model": new bullet codifying *why* the main ruleset omits this rule. References README for the configured state. Operator action (out of scope for this PR's diff but called out in both docs): untick "Require branches to be up to date before merging" on Settings -> Rulesets -> Main in the GitHub UI. Once that's done, future develop -> main release merges land without admin bypass. PR #80 itself can either ride this PR (rebased to a new develop head) or land via one-time admin bypass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the template documentation to explain why GitHub’s “Require branches to be up to date before merging” rule must be disabled on the main ruleset when using a forward-only develop model, and clarifies that the rule remains appropriate on the develop ruleset.
Changes:
- Update
README.mdrulesets guidance to move the “up to date” requirement out of shared settings and explicitly mark it as Develop-only. - Add an explicit branching-model rationale in
AGENTS.mddocumenting why themainruleset omits the “up to date” requirement.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| README.md | Clarifies ruleset settings split between Develop vs Main, and documents the “up to date” rule as intentionally disabled on Main. |
| AGENTS.md | Codifies the branching-model rationale for omitting the “up to date” requirement on Main and points back to README for configured state. |
Two valid findings: 1. README intro for the rulesets section said develop and main "intentionally diverge on two rules" — actually three (allowed merge methods, require linear history, and the up-to-date requirement). Reworded to enumerate all three. 2. AGENTS.md bullet said develop is "strictly ahead in content" immediately after a release — that's wrong, right after the merge develop and main are content-equivalent (main just has an extra merge commit). Also "The only way" was too absolute (rebasing/rewriting develop's history would technically also satisfy the check, just contradicts forward-only). Reworded to describe both the post-release state and that other technical workarounds exist but conflict with the doctrine. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two valid Copilot corrections on the prior pass: 1. README.md's explanation said "main has a new merge commit whose first-parent walk doesn't appear in develop's history" — that's not strictly accurate. When main's pre-release tip is already reachable from develop (the common case after one back-merge or any shared ancestry), the first-parent walk does overlap with develop's history. The thing that's NOT reachable is the new merge commit itself. Reworded to focus on merge-commit reachability, not first-parent walks. 2. AGENTS.md claimed "right after a develop → main release the two branches are content-equivalent." Dual-target bots can land content on main without develop seeing it yet (codegen-main run succeeding while codegen-develop fails, Dependabot security PR to main, etc.), so content-equivalence isn't guaranteed. Reframed the explanation purely in graph terms (no content claim), keeping the rationale honest regardless of whether the two branches are content-equivalent at that moment. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ptr727
enabled auto-merge (squash)
May 12, 2026 05:02
Merged
5 tasks
ptr727
added a commit
that referenced
this pull request
May 12, 2026
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves the root cause behind why PR #80 (the develop → main release) is blocked by "the head branch is not up to date with the base branch". The forward-only develop model PR #78 codified is fundamentally incompatible with the ruleset's
Require branches to be up to date before mergingrule, and the README's documented "shared settings" block hid the contradiction.What's actually happening
The "up to date" check is graph-based: it asks "is main's tip commit reachable from develop?", not "does develop have main's content?". After any develop → main release, main has a new merge commit (e.g.
fb10a16from PR #77) whose first-parent walk isn't in develop's history. Develop is strictly ahead in content but "behind" in graph terms.Historical back-merge commits (
ffb9e64,5ce95cf) had been quietly compensating for this — each one created a develop commit whose second parent was main's release-merge commit, making main's tip reachable from develop. PR #78 codified forward-only and forbade back-merges, but the README rulesets section still listedRequire branches to be up to dateas a shared setting. The contradiction was invisible until the first release without a preceding back-merge tried to land — which is PR #80.What this PR changes
README.md"Rules / Rulesets": moveRequire branches to be up to date before mergingout of "Shared settings" and into the Develop-only ruleset entry (where it's standard hygiene for feature → develop merges). Add 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, with a pointer to README for the configured state.What you'll need to do in the GitHub UI
Untick
Require branches to be up to date before mergingin Settings → Rulesets → Main. That's a config change, not a code change, and rulesets are security-sensitive so it stays your direct action. After:gh pr merge --merge(no admin bypass needed).Test plan
--admin.