Skip to content

merge-must-land-on-the-default-branch/4: The warning comment, the status and explain views, and documents - #993

Merged
bwmatson merged 7 commits into
mainfrom
spec/merge-must-land-on-the-default-branch/4
Nov 17, 2026
Merged

bwmatson merged 7 commits into
mainfrom
spec/merge-must-land-on-the-default-branch/4

Conversation

@bwmatson

Copy link
Copy Markdown
Owner

Start here

Already verified by the pipeline

  • Tests were committed first and seen to fail first.
  • unit-test result: passed
  • Review took 3 review rounds

Review tier: light — the planned estimate is light

Why

This pull request builds part of change merge-must-land-on-the-default-branch; this is the change's reason.

A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged. The kit keeps a merged parent's remote branch while a child is owed a move, so GitHub never retargets the child itself; the kit's own retarget (update_pr) never raises and only logs, so one failure leaves the child on the old base with nothing recorded; and a person merging the child on the forge sees nothing wrong. The pipeline then records the unit as `merge

… The full reason is in openspec/changes/merge-must-land-on-the-default-branch/proposal.md.

What this pull request does

When a stacked pull request's base branch has merged and its retarget to the default branch is still pending, the pipeline posts one 'do not merge' warning on that pull request and shows the state in its status and explain views.

  • Each poll round looks for in-review units whose pull request still targets the branch of a merged or satisfied ancestor in the same repo. For each one it finds, it posts a single warning comment carrying a marker line, naming the branch the PR should target and telling the reader not to merge yet.
  • The ids of warning comments are recorded in the own-posts record, so the poller does not read them as reviewer feedback, and a later round, including one after a failed retarget, does not post a second warning.
  • The code host is asked for a pull request's current base only when one of that unit's own ancestors has merged with a branch other than the wanted base. A round with no such ancestor makes no extra host read.
  • A shared FindingForge stand-in (tests/forges/stand_in.py), matching on marker and exact body, replaces the two per-file copies the tests used.
  • The status and explain views and the documents describe the pending-retarget warning.

Based on main, with nothing unmerged beneath it — ready to merge whenever the checks look right.

Unit merge-must-land-on-the-default-branch/4 of change merge-must-land-on-the-default-branch, task group(s) 4, 5.
Spec: openspec/changes/merge-must-land-on-the-default-branch/ in the planning repo.

Assumptions

This unit assumes nothing unmerged: everything it builds on is already in main.

Verification

This is a unit-test unit: everything it needs is fakes, fixtures or throwaway containers, so GitHub Actions runs the whole of it. No e2e-test run was required.

Left for later

Approved, with these recorded rather than blocking:

  • warn_base_merged in pipeline/events.py still repeats the in-review/pr/base_of/base_on_host selection of retry_retargets. Each one now reads the host only for a unit with a merged ancestor, so the doubled read is bounded. Folding the warning into retry_retargets as a callback that receives the on_host value already read would remove the second copy of the stale-base rule (one copy skips mid_move units and the other does not).
  • The new test test_the_host_is_not_asked_about_a_unit_that_does_not_depend_on_the_merged_unit relies on stored_unit's default repo matching the fixture's repo. Passing repo= explicitly would keep the test meaningful if either default changes.

How this was built

Tests were committed first and seen to fail before any implementation existed; the commit order is checked mechanically; lint, formatting and types pass at the tip.


Opened by the spec-driven pipeline. The build agent never merges. The pipeline merges only
a unit review classified auto and policy allowed; a person merges any other, after checking
the stack order above.

The tests come first and fail until the implementation.

A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged.

Unit: merge-must-land-on-the-default-branch/4
With this in, the tests of the previous commit pass.

A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged.

Unit: merge-must-land-on-the-default-branch/4
The tests come first and fail until the implementation.

A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged.

Unit: merge-must-land-on-the-default-branch/4
With this in, the tests of the previous commit pass.

A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged.

Unit: merge-must-land-on-the-default-branch/4
… (checks, round 1)

Unit: merge-must-land-on-the-default-branch/4
… (review round 1)

Unit: merge-must-land-on-the-default-branch/4
… (review round 2)

Unit: merge-must-land-on-the-default-branch/4
@bwmatson bwmatson added change-merge-must-land-on-the-default-branch The change this pull request belongs to checking In review, but its checks are still running review-light Review asks for a light look from a person in-review Built and waiting for human review and removed checking In review, but its checks are still running labels Nov 17, 2026
@bwmatson
bwmatson merged commit 130d558 into main Nov 17, 2026
5 checks passed
@bwmatson bwmatson added settling Merged; waiting for its checks to complete and removed in-review Built and waiting for human review settling Merged; waiting for its checks to complete labels Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

change-merge-must-land-on-the-default-branch The change this pull request belongs to review-light Review asks for a light look from a person

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant