Skip to content

docs: DocxDiff default migration plan (D4 execution)#245

Open
JSv4 wants to merge 1 commit into
mainfrom
docs/docxdiff-default-migration-plan
Open

docs: DocxDiff default migration plan (D4 execution)#245
JSv4 wants to merge 1 commit into
mainfrom
docs/docxdiff-default-migration-plan

Conversation

@JSv4

@JSv4 JSv4 commented Jun 27, 2026

Copy link
Copy Markdown
Owner

Adds a single planning doc — docs/architecture/docxdiff_default_migration.md — laying out how to promote DocxDiff to the blessed default comparison engine and demote WmlComparer to a documented, still-reachable legacy engine (execution plan for decision D4).

Docs-only; no code or behavior change in this PR.

What the plan captures

  • Current state — the green/ratcheted parity evidence (179/179 GetRevisions, 39/39 markup, 84/84 consolidate-soundness) and the asymmetric client wiring that blocks a clean flip today.
  • Milestones (sequenced, gated):
    • M-A (BLOCKING) — close the four multi-reviewer Consolidate edge-gaps before the flip: note-scope N-way merge, structural table changes, cross-reviewer split/merge, cross-kind note nesting.
    • M-B — add one shared engine selector across WASM / npm / tools/redline, seeded to WmlComparer (the default is not flipped here).
    • M-C — author + run a Microsoft Word manual-verification checklist (artifact doesn't exist yet).
    • M-D — burn-in window with explicit pass criteria.
    • M-E — the flip (default → DocxDiff) + legacy re-labeling in docs and /// remarks only (no [Obsolete] this cycle).
    • M-F[Obsolete] deferred to a future major.
  • Gate exit criteria (G2, D4), four-layer ripple checklist, risk/rollback (the engine selector is the rollback), and a definition of done.

Decisions baked in (per request)

  • Consolidate gaps block the flip (not accepted-scope).
  • Legacy marking is docs + XML-doc only first; [Obsolete] deferred.
  • Engine flag with one shared default; WmlComparer stays the default during the migration — the flip to DocxDiff is M-E, after the gates clear.

Two decision points are deliberately left open in §8 rather than pre-decided: the flip's FormatComparison default (ModeledOnly vs Full) and its semver bump (major vs minor).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant