Skip to content

Upgrade Docxodus to v7.0.0 and expose its comparison-engine flag#25

Merged
JSv4 merged 5 commits into
mainfrom
upgrade-docxodus-v7
Jul 10, 2026
Merged

Upgrade Docxodus to v7.0.0 and expose its comparison-engine flag#25
JSv4 merged 5 commits into
mainfrom
upgrade-docxodus-v7

Conversation

@JSv4

@JSv4 JSv4 commented Jul 10, 2026

Copy link
Copy Markdown
Owner

Upgrades the vendored Docxodus submodule from v5.4.2 to v7.0.0 and exposes v7.0.0's new
--engine=wmlcomparer|docxdiff selector as an engine= kwarg on DocxodusEngine.

engine = DocxodusEngine()
engine.run_redline("Reviewer", original, modified)                     # wmlcomparer (default)
engine.run_redline("Reviewer", original, modified, engine="docxdiff")  # new IR engine

wmlcomparer stays the default. When engine is omitted no --engine flag is emitted at all,
so the argv is byte-identical to the pre-v7 one.

The upgrade drags .NET 10 in with it

Docxodus v7.0.0 retargets net8.0net10.0. That reaches past the submodule:

  • Root global.json → SDK 10.0.0. It governs SDK selection because dotnet resolves
    global.json from the working directory, not the project path, so docxodus/global.json
    is never consulted by our builds.
  • The three CI dotnet-version pins → 10.0.x.
  • build_differ.py hardcoded net8.0 in its publish path. The two engines now target different
    frameworks, so ENGINES carries a per-engine tfm.

Only one SDK is provisioned. The .NET 10 SDK builds the net8.0 ooxmlpowertools project
self-contained; its binary still reports Revisions found: 9. Verified locally on linux-x64
and cross-built for linux-arm64. The Windows and macOS wheel builds are exercised for the
first time by this PR's CI.

Contributors now need a .NET 10 SDK — a stock .NET 8 box can no longer build the Docxodus
engine at all. Documented in the README and developer guide.

docxdiff silently drops three settings, so Python rejects them

On the docxdiff branch, DocxCompare.ToDocxDiffSettings maps only a subset of
WmlComparerSettings. It drops detail_threshold, simplify_move_markup, and
detect_format_changes — the CLI accepts them, prints no diagnostic, and produces output as if
they were never passed. Confirmed empirically: --engine=docxdiff --detail-threshold=0.9
yields the same result as --engine=docxdiff alone.

Passing any of those three alongside engine="docxdiff" now raises ValueError before we shell
out. Rejection is on key presence, regardless of value: two of the three are no-ops at their
defaults, so a value-sensitive rule would raise for detect_format_changes=False but not for
detect_format_changes=True — a worse contract than "naming a WmlComparer-only knob while
asking for docxdiff is an error."

docxdiff does honour detect_moves, case_insensitive, conflate_spaces,
move_similarity_threshold, move_minimum_word_count, and date_time.

The two engines report different revision counts

On tests/fixtures/, wmlcomparer finds 9 revisions and docxdiff finds 11. Different
algorithms, both correct. Both counts are asserted: the 9 guards against an accidental default
flip, the 11 against a silent no-op where --engine never reached the binary.

Also scoped the README's move-detection warning to WmlComparer. It told every caller to pair
detect_moves with simplify_move_markup, but docxdiff honours the former and rejects the
latter, so a docxdiff user following the docs hit a ValueError with no available mitigation.
DocxDiff renders moves natively; whether Word's ID-collision bug affects its move markup is
untested and the docs no longer imply either way.

Testing

40 tests pass. Version bumped 0.2.10.3.0 (the bump also re-keys the binary-extraction
cache, which is keyed by package version).

JSv4 added 5 commits July 10, 2026 01:37
Docxodus v7.0.0 retargets to net10.0. The root global.json governs SDK
selection for builds run from the repo root, so it moves to 10.0.0; the
three CI dotnet-version pins follow.

The ooxmlpowertools project stays on net8.0 and the .NET 10 SDK builds it
self-contained without complaint, so only one SDK is provisioned. Because
two target frameworks are now in play, build_differ.py carries an explicit
per-engine tfm rather than a hardcoded net8.0 publish path.
Docxodus v7.0.0 added --engine=wmlcomparer|docxdiff. Surface it as a kwarg,
normalized the way the CLI's own TryParseEngine normalizes it. Omitting the
kwarg emits no flag at all, so the default argv is unchanged.

The docxdiff branch of DocxCompare.ToDocxDiffSettings drops detail_threshold,
simplify_move_markup, and detect_format_changes, and the CLI accepts them
there without a diagnostic. Rejecting them on key presence -- whatever the
value -- keeps that from becoming a Python-level footgun: a caller who tunes
granularity under docxdiff would otherwise get untuned output and no signal.
wmlcomparer finds 9 revisions and docxdiff finds 11 on the same pair. The
counts differ because the algorithms differ, so both are asserted: the 9
guards against an accidental default flip, and the 11 against a silent
no-op where --engine failed to reach the binary.
Bump to 0.3.0: the vendored engine jumps v5.4.2 -> v7.0.0 and gains a
comparison algorithm, and contributors now need a .NET 10 SDK to build it
at all. Records that docxdiff reports a different revision count than
wmlcomparer on identical input -- expected, not a defect.
The warning told every caller to pair detect_moves with simplify_move_markup,
but docxdiff honours the former and rejects the latter, so a docxdiff user
following the docs hit a ValueError with no available mitigation. Scope the
warning and say what docxdiff does instead -- without claiming it is free of
the Word bug, which is untested.

test_docxodus_explicit_wmlcomparer_matches_default now parses and compares the
two revision counts rather than asserting each contains "9" independently, so
the test checks the equivalence its name promises.
@JSv4 JSv4 force-pushed the upgrade-docxodus-v7 branch from 6562725 to bbc829e Compare July 10, 2026 06:42
@JSv4 JSv4 merged commit 6514860 into main Jul 10, 2026
13 checks passed
@JSv4 JSv4 deleted the upgrade-docxodus-v7 branch July 10, 2026 06:46
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