Skip to content

merge-must-land-on-the-default-branch/1: Record a merge only when it is on the default branch - #987

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

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

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: full — the reviewer classified it full

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

A unit's pull request is recorded as merged only when its work actually reached the default branch. Merges into another unit's branch either wait for that unit or are held for a person.

  • A pull request merged into a branch other than the default is no longer recorded MERGED: when the unit whose branch it went into has already merged (or no such unit exists), the unit is held with cause landed_off_default and a note naming the pull request, the base branch and the default branch, …
  • A merge into a still-open unit's branch leaves the unit SETTLING with a note that it lands when that unit does, even after its checks complete.
  • When the parent unit later lands, a settling child settles to MERGED if its merge commit is on the parent's branch, which handles a squash landing whose new commit is not a descendant of the child's commit. Otherwise it is held as landed_off_default, so it never waits forever.
  • landing_check gains merged_on_branch (an ancestry check against any remote branch after a fetch), and merged_on_default now delegates to it.
  • The hold reaches the unit's graph thread like a person's hold, and is deferred when the unit's branch is busy.

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

Unit merge-must-land-on-the-default-branch/1 of change merge-must-land-on-the-default-branch, task group(s) 1.
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:

  • src/agent_build_kit/pipeline/events.py:1192 — After the parent lands, the squash rule checks the child's merge commit against refs/remotes/origin/<parent branch>. While the parent was open, nothing fetched that branch: the first settled only fetches the default branch, and on_merged does the same. If the parent's branch is gone from the remote by then (the pipeline's own delete_branch after a parent leaves, or the host deleting it on merge), the fetch fails. The check then reads a stale tracking ref that predates the child's merge, so the child is held landed_off_default even though the squash carried its work.

…and 1 more.

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/1
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/1
…und 1)

Unit: merge-must-land-on-the-default-branch/1
…nd 1)

Unit: merge-must-land-on-the-default-branch/1
…und 1)

Unit: merge-must-land-on-the-default-branch/1
…nd 2)

Unit: merge-must-land-on-the-default-branch/1
@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-full Review asks for a full read 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 added this pull request to stack #992 November 17, 2026 12:05
@bwmatson
bwmatson merged commit ee1becf 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-full Review asks for a full read from a person

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant