drop-superseded.md

# Dropping a superseded mid-stack commit

Remove a commit whose change a later commit reverses - a *move-then-unmove* -

so the landed history never carries the churn. Reverting on top reaches the

same tree with no rewrite but bakes both the move and its reversal into

permanent history; dropping at source costs a conflict cascade now and, where

the commit's revision has been reviewed, each reviewer their place in it.

Dropping usually wins; the reviewed revision is the exception.

The commands for each step are in the mechanics reference for your VCS, under

"Drops", numbered as the steps are here. Step 1's searches are git's, and a

colocated jj checkout runs them too.

## When this applies

Both must hold:

1. **Its change is one you're reversing** - either a later commit *already*

   undid it (net-zero in the final tree), or a later commit obsoleted its

   *rationale* and you're choosing to revert it, in which case the change

   survives to the final tree until you do.

2. **Nothing above it uses what it introduced, other than editing it in

   place.** A later commit that only edits text the dropped commit touched is

   bounded (step 3 redirects the edit); one that uses a symbol, API or file it

   added from elsewhere is not, and dropping cascades through it.

A net-zero commit that still tells a useful incremental story can stay; a pure

move-then-unmove documents a reversed decision and cannot.

Start from the superseding commit's own account of what it removes or reworks

(its message). A commit that lays durable scaffolding a later commit *builds

on* is not net-zero, and dropping it loses real work.

There is no cheap mechanical test: reverse-applying the commit's patch to the

tip reports false "superseded" on clearly durable commits, since later commits

shift context around surviving changes. The drop itself is the test; step 5

says how to read it.

## Procedure

### 1. Bound the blast radius first

For each symbol or API the commit adds:

```

git log -S'<symbol>' <commit>..<branch>     # commits above that touch it

git log <commit>..<branch> -- <added-path>  # commits above that edit a file it adds

```

`-S` counts occurrences of the string, so a commit that edits the body of a

file the dropped commit adds is invisible to it; the path form finds that

commit, and each commit either form names is a conflict to expect in step 3.

An empty result means the cascade is bounded to commits touching the *same*

code. Search the whole tree with `-S`, not `-- <file>`: a commit above that

consumes the symbol from somewhere else is exactly the dependency condition 2

rules out, and a path filter hides it.

### 2. Drop it

Back the branch up unless the mechanics reference's backup already exists,

then remove the commit and replay every commit above it onto its parent. Its

message and the reverser's go with it: harvest what the diff cannot show first

(`SKILL.md`, Phase 3).

### 3. Resolve the cascade faithfully

Expect one conflict per commit that built on the dropped one, plus any commit

that merely trimmed a comment near the dropped code. The reverser itself does

not conflict when the resolutions below it were faithful: its change is

already in the tree, so it comes out empty; the mechanics reference says how

each VCS reports that and what to confirm. A reverser that conflicts on

anything but the deletion of a file the drop already removed means a

resolution below it diverged from the reverser's form. The usual shape is

the dropped commit's additions appearing as *context re-adds* (the merge

thinks the later commit is re-introducing the symbols): drop those re-adds and

repoint reads to the pre-move form. A commit that only *modified* what the

dropped commit added conflicts as delete/modify instead, with no re-add to

drop: keep its real change, rebased onto the pre-move form (the edit rides the

cascade to wherever the text lives after the drop, the churn rule in

`SKILL.md`), and never resolve it by the deletion alone. Where re-targeting

the hunk to the pre-move path does not apply cleanly, insert the change by

hand and check it byte for byte against the backup tip at that path. Check any

whole-tree invariant (the mechanics reference, verifying every commit) at the

resolved commit too. Keep each later commit's *real* changes; drop only what

the dropped commit had introduced.

### 4. Finish coupled changes at their source

Dropping the commit may fix one owner (e.g. the implementation and its test)

while a parallel owner elsewhere still carries the reversed form. Complete that

at the commit that *introduced* it, not on top, so that commit introduces the

correct form with no separate add-then-remove.

### 5. Validate

- **Already net-zero:** the diff from the backup tip to the result must be

  **empty**. Non-empty means the commit had surviving changes: return to the

  backup and keep it. The resolution must have been faithful; forcing the

  final content makes the diff trivially empty and proves nothing.

- **Deliberate reversal:** the tree changes by design, so build and test

  instead. The drop is sound only if the result is behavior-neutral on the

  default path and any remaining failures are *unrelated* gaps, not

  regressions.

## The review-tool side

`moz-phab submit` updates the surviving revisions but neither abandons the

dropped commit's revision nor re-parents around it, so the orphan stays

bridged into the stack by stale "Depends On" edges. `moz-phab reorg`

recomputes the edges and abandons the orphan; confirm in its preview that the

orphan is the *only* thing it proposes abandoning, per "Review-tool side" in

`SKILL.md`. Never re-push without explicit approval.