From 8e6916dc05bae9bdd22c4b2a6bff3877e6eeace9 Mon Sep 17 00:00:00 2001 From: JSv4 Date: Sat, 24 Oct 2026 10:09:30 -0500 Subject: [PATCH] chore: prepare 2.0.0 release and migration guide --- README.md | 33 +++++++++++++++++-- docs/quickstart.md | 2 ++ packages/core/README.md | 7 +++- .../core/src/python_redlines/__about__.py | 2 +- packages/docxodus/README.md | 2 +- 5 files changed, 41 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2b5a719..3284226 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,9 @@ with open("redline.docx", "wb") as f: That's the whole thing. The rest of this README covers the other engines, comparison settings, and how the packages are built and distributed. +Version 2.0.0 bundles Docxodus v14.1.0. Its comparison output can differ from +1.0.0; see [Upgrading to 2.0.0](#upgrading-to-200) before updating an existing deployment. + ### ⚠️ Breaking in 1.0.0: `WmlComparer` is gone; DocxDiff is the only algorithm Docxodus v11.0.0 **removed `WmlComparer`**, the algorithm this library ran by default for its @@ -164,7 +167,7 @@ argument raises `ValueError`. ### 1. `DocxodusEngine` — the default **[Docxodus](https://github.com/JSv4/Docxodus)** is an actively-maintained .NET 10.0 document -toolchain. Python-Redlines 1.1.0 bundles Docxodus v14.1.0. Its `DocxDiff` algorithm +toolchain. Python-Redlines 2.0.0 bundles Docxodus v14.1.0. Its `DocxDiff` algorithm models the document as an intermediate representation rather than a stream of runs, which lets it attribute a change to the exact paragraph, cell, row, or section it touched: @@ -224,7 +227,7 @@ selects the wheel matching your platform automatically. Instantiating an engine companion package is not installed raises `EngineNotInstalledError` telling you which extra to install. -From 1.0.1 onward, extras pin each engine companion to the wrapper's exact release +From 2.0.0 onward, extras pin each engine companion to the wrapper's exact release version. Older published releases still have unconstrained extras: if you need 0.3.0, install both `python-redlines[docxodus]==0.3.0` and `python-redlines-docxodus==0.3.0` explicitly. @@ -285,6 +288,32 @@ The 0.3.0-era warning that `detect_moves=True` needed `simplify_move_markup=True "unreadable content" dialog applied to `WmlComparer`'s move markup. It does not apply here — `DocxDiff` emits move markup natively and has no such mitigation, because it needs none. +## Upgrading to 2.0.0 + +2.0.0 bundles Docxodus v14.1.0. The major version makes the change in comparison +output an explicit upgrade: markup, revision granularity and revision counts can +differ from 1.0.0. The Python call signatures and supported settings are unchanged. + +1. **Install the matching wrapper and engine through the extra:** + + ```bash + pip install --upgrade 'python-redlines[docxodus]==2.0.0' + ``` + + All extras now require companion packages at exactly the wrapper's version. + Update lockfiles or separately pinned companions to 2.0.0 as well. +2. **Review representative redlines and refresh output snapshots.** A single-character + CJK edit now marks just the changed character. Edits inside unchanged content-control + or custom-XML wrappers can be marked inside the wrapper instead of replacing it whole. + The project's existing fixture still reports 10 revisions; that does not imply identical + output for other documents. +3. **Check error reporting.** Nonzero engine exits raise `EngineExecutionError`, a + `subprocess.CalledProcessError` subclass. Existing handlers still work; the message now + includes captured stderr and stdout, and the original exception attributes remain available. + +`XmlPowerToolsEngine` remains available and deprecated. If upgrading from 0.3.0, also +apply the 1.0.0 migration steps below; the removed WmlComparer settings remain unsupported. + ## Upgrading to 1.0.0 **If you called `run_redline` with no keyword arguments, nothing in your code changes.** Your diff --git a/docs/quickstart.md b/docs/quickstart.md index f14ba0c..a35f772 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -79,6 +79,8 @@ algorithm they configured — see ### See also +- [Upgrading to 2.0.0](https://github.com/JSv4/Python-Redlines#upgrading-to-200) — + engine output changes, matching companion packages and error reporting - [How to compare two Word documents programmatically in Python](tutorials/how-to-compare-word-documents-python.md) — a step-by-step tutorial covering this same flow in more depth - [Live demo](https://redlines.opensource.legal) — try a comparison in your browser diff --git a/packages/core/README.md b/packages/core/README.md index bb08a40..922b3ae 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -32,11 +32,16 @@ redline_bytes, stdout, stderr = engine.run_redline( with WmlComparer. See the [project README](https://github.com/JSv4/Python-Redlines#comparison-settings-docxodusengine-only) for supported settings. -From 1.0.1 onward, each extra pins its companion package to the same release +From 2.0.0 onward, each extra pins its companion package to the same release version as the wrapper. For older releases, pin both packages explicitly (for example, `python-redlines[docxodus]==0.3.0` and `python-redlines-docxodus==0.3.0`). Existing published metadata is unchanged. +2.0.0 bundles Docxodus v14.1.0. Python call signatures and supported settings +are unchanged from 1.0.0, but comparison markup and revision granularity can differ. +Review representative redlines when upgrading; see the +[2.0.0 migration guide](https://github.com/JSv4/Python-Redlines#upgrading-to-200). + An unsuccessful engine exit raises `EngineExecutionError`, a subclass of `subprocess.CalledProcessError`. Its message includes the captured stderr and stdout; `returncode`, `cmd`, `stdout`/`output`, and `stderr` remain available. diff --git a/packages/core/src/python_redlines/__about__.py b/packages/core/src/python_redlines/__about__.py index 52b09ba..9a4ea48 100644 --- a/packages/core/src/python_redlines/__about__.py +++ b/packages/core/src/python_redlines/__about__.py @@ -1,4 +1,4 @@ # SPDX-FileCopyrightText: 2024-present U.N. Owen # # SPDX-License-Identifier: MIT -__version__ = "1.1.0" +__version__ = "2.0.0" diff --git a/packages/docxodus/README.md b/packages/docxodus/README.md index 36d176f..80f7571 100644 --- a/packages/docxodus/README.md +++ b/packages/docxodus/README.md @@ -3,7 +3,7 @@ Compiled Docxodus redline engine binary for [`python-redlines`](https://pypi.org/project/python-redlines/). -Version 1.1.0 bundles the engine built from Docxodus v14.1.0. +Version 2.0.0 bundles the engine built from Docxodus v14.1.0. This package only contains the platform-specific engine binary. Install it via the `python-redlines` extra rather than directly: