InsightSoftwareConsortium / InsightSoftwareConsortium/ITK
COMP: Implement the Phase-3 equivalence check in rewrite-history-merge-preserving.py
- Dominant language
- C++
- Stars
- 1.7k
- Forks
- 748
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 64
Description
`rewrite-history-merge-preserving.py` documents a four-phase model, but Phase 3 — verifying that the Phase-2 rewritten tip has the same tree as the Phase-1 reference — has no implementing function. The check the script exists to guarantee is left to the operator.
What is and isn't implemented
Verified on `upstream/main` (script merged via `1f41862f3c3`):
| Phase | Documented at | Implemented by |
|---|---|---|
| 1 — reference tree | docstring | `run_phase_1_reference()` |
| 2 — merge-preserving rewrite | docstring | `run_phase_2_rewrite()` |
| **3 — VERIFY tip ≡ reference** | docstring line 36 | ❌ **nothing** |
| 4 — Mode A merge | docstring | `assert_topology_preserved()` (topology only) |
`grep -c 'def run_phase_3\|def verify_phase'` returns **0**.
`--phase-1` prints the reference tree hash and exits; the default Phase-2 path
never compares against it. Nothing closes the loop, so a per-commit rewrite
that silently disagrees with the format-once-at-main tree passes unnoticed.
Proposed work
Add a `run_phase_3_verify(reference_tree, branch)` that diffs the rewritten tip
against the Phase-1 reference and exits non-zero on any difference, and wire it
into the Phase-2 path (or a `--verify-against ` flag) so the gate is
automatic rather than a documented manual step.
~30 lines. Until it exists, the manual gate is `git diff --stat HEAD`,
which must be empty.
Contributor guide
Research direction
Start in Utilities/Maintenance/RemoteModuleIngest/rewrite-history-merge-preserving.py, reading run_phase_1_reference(), run_phase_2_rewrite(), and assert_topology_preserved(). Add the Phase-3 verification described in the issue, wire it into the Phase-2 path or the proposed flag, and confirm that git diff --stat HEAD is empty for matching trees and the command exits non-zero for differences.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, python
- Domain
- cli, tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100