Compare commits

...

1 Commits

Author SHA1 Message Date
diegosouzapw
b470798f23 docs(ci): AGENTS.md says how a PR lands on a release branch and how a sync-back lands
The sync-back section prescribed a direct push that the default branch has refused since
the ruleset Require PR on default branch: a sync-back lands through a pull request merged
with a merge commit, which scripts/release/sync-next-cycle.mjs opens since #20645.

New section Landing on a release branch: omni-queue. In shadow mode a manual merge waits
for the queue's verdict on the PR's final head (green checks prove a PR against the base
they ran on: #19132); in live mode the label is the landing.
2026-11-21 02:54:24 -03:00
2 changed files with 27 additions and 6 deletions

View File

@@ -326,12 +326,33 @@ If red: never treat or "fix" the inherited failures in your branch (a base-red f
freeze-gated `fix/release-vX.Y.Z-basereds` PR); a PR opened anyway carries
`⚠️ base-red inherited: #<issue>` in its body. Full procedure: `docs/ops/WORKTREE_ISOLATION.md`.
### Sync-back landings are fast-forward, never squash
### Landing on a release branch: omni-queue
A `main → release/vX+1` sync-back lands as the merge commit it already is
(`git push origin <head>:refs/heads/release/vX+1`), never squashed — a squash drops `main` from
the release ancestry and the next sync-back re-conflicts on every file (551 on v3.8.50 → v3.8.51).
After landing, `git merge-base --is-ancestor origin/main origin/release/vX+1` must be true.
`release/vX.Y.Z` branches are served by the project's merge queue (runbook:
[`docs/ops/OMNI_QUEUE.md`](docs/ops/OMNI_QUEUE.md)). Read its `mode` in
`config/merge-queue/config.json` on the default branch before landing anything:
- **`shadow`** — the queue tests but lands nothing; merges are manual. Green checks on a PR head
prove the PR against the base they ran on, not against today's base, so before a manual merge
apply the `omni-queue` label at the PR's final head and wait for the queue's verdict on that
head (`npm run queue -- why <PR>`, `npm run queue -- history --base <branch>`): `would-land` →
merge; `culprit-found` / `would-dequeue` → do not merge, fix first. A merge train whose full CI
is green on the current base tip, or a head that already contains the base tip, needs no
separate verdict.
- **`live`** — the `omni-queue` label is the landing. Never run a merge command or push against
the branch: its ruleset refuses both.
Apply the label only to a PR the owner authorized you to land; a PR that touches a protected path
also needs `protected-approved`, which is the owner's decision per PR. Never push to
`omni-queue-state` or `omni-queue/**`.
### Sync-back landings are merge commits, never squash
A `main → release/vX+1` sync-back lands through a pull request merged with a merge commit
(`scripts/release/sync-next-cycle.mjs` opens it; the default branch refuses a direct push), never
squashed — a squash drops `main` from the release ancestry and the next sync-back re-conflicts on
every file (551 on v3.8.50 → v3.8.51). After landing,
`git merge-base --is-ancestor origin/main origin/release/vX+1` must be true.
Steps + baseline-freeze check: `docs/ops/WORKTREE_ISOLATION.md` → "Sync-back landings".
---

View File

@@ -2001,7 +2001,7 @@ The three uses:
- **Hotfix**: a commit that cannot wait for a batch.
- **Sync-back landing**: the `main → release/vX+1` merge commit, pushed as the merge commit it
already is (see AGENTS.md → "Sync-back landings are fast-forward, never squash").
already is (see AGENTS.md → "Sync-back landings are merge commits, never squash").
- **Base repair**: a fix to a red base that the maintainer lands directly instead of through a
batch.