golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(#3268): next does require up-to-date; correct CONTRIBUTING and branching (#3269)

Browse Source 
CONTRIBUTING.md said branch protection on `next` has the "up-to-date before
merging" flag DISABLED and that "the rebase treadmill is gone for the 95%
case". docs/branching.md repeated it three times. The live protection says
the opposite:

  $ gh api repos/open-gsd/gsd-core/branches/next/protection \
      --jq '.required_status_checks.strict'
  true

This is not a cosmetic nit — it misstates the cost model of every PR in the
repo. A contributor plans for no rebase, then finds their PR BEHIND at merge
time. And because the push gate binds its pass marker to an exact sha, that
rebase invalidates the marker and forces a full remote re-verification plus
another CI cycle. Believing the treadmill is gone is how you pay for it
unplanned, late, on a PR that looked finished — observed on PR #3261.

Both files now state the real requirement, show the one-line command to
verify it, and name the sha-invalidation consequence with the practical
advice that follows from it: rebase LAST, immediately before pushing for
review, rather than paying for a verification you are about to discard.

What was true in the original text is kept: `next` moves far less often than
`main` did, so the rebase frequency really is much lower. The claim that was
wrong was that the requirement does not exist.

Closes #3268

Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
2026-08-09 17:25:31 -04:00
committed by GitHub
parent 2e2b8ba4a7
commit 12bda8e844
2 changed files with 41 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
CONTRIBUTING.md
View File

@@ -147,12 +147,21 @@ If you target the wrong branch by accident, the `PR Target Validator`
workflow will post a comment with the one-line fix (click "Edit" by the PR
title and change the base branch — no need to recreate the PR).
**Why this matters:** Under the old single-branch model, every PR required
rebasing onto `main` because branch protection required "up-to-date before
merging" and `main` moved on every merge. With `next` as the integration
branch and that flag disabled on `next`, concurrent PRs can merge in any
order as long as they don't conflict on the same lines. The rebase
treadmill is gone for the 95% case.
**Why this matters:** Under the old single-branch model, every PR rebased onto
`main`, which moved on every merge. `next` moves far less often — only when
another PR to `next` lands — so in practice you rebase much less.
**But `next` does still require "up-to-date before merging".** Branch
protection has `required_status_checks.strict = true`; check it yourself with
`gh api repos/open-gsd/gsd-core/branches/next/protection --jq '.required_status_checks.strict'`.
If another PR lands while yours is open, yours goes `BEHIND` and must be
rebased before it can merge.
Budget for that, because the rebase is not free here: **it changes your HEAD
sha, which invalidates the sha-bound pass marker the push gate reads**, so a
rebase means re-running the full remote verification and another CI cycle
before the gate clears again. Rebase *last* — immediately before you push for
review — rather than paying for a verification you are about to discard.
---