Child of #256. Depends on #760 (the changed-chapter substrate). See the reversal comment.
Why this one is the highest-value of the three
ucdavis/win/.github/scripts/create-docx-tracked-changes.py (8.6 KB) compares the PR's DOCX output against the published DOCX on gh-pages and produces a version carrying Word tracked changes.
That is the feature that lets a co-author who does not use GitHub review a pull request. They open a Word document, see tracked changes, and comment — no branch, no diff, no PR UI. For a lab writing manuscripts in Quarto with collaborators who review in Word, this is the single most useful thing in the set.
Proposed input on preview: docx-tracked-changes (boolean, default false). Requires the caller to be rendering DOCX at all, so it composes with #758's formats work.
The one new dependency
python-docx, imported lazily inside create_docx_with_tracked_changes (create-docx-tracked-changes.py:55-58) with a warning-and-continue fallback at :136.
That fallback is the thing to remove. A missing python-docx currently degrades to copying the new DOCX unchanged (:62) — so the output is a document with no tracked changes that is indistinguishable from a document where nothing changed. A reviewer would read "no edits" from a dependency failure. Under shared/principles/fail-fast.md that must be a stated error, and the composite should install the dependency rather than hoping for it.
Rewrite, not copy
3 check=False and 2 broad except. Beyond the dependency fallback:
Tests
python-docx is a real dependency, so unit-test the diff/annotate logic directly against generated .docx fixtures built at runtime — do not commit binary fixtures, which would land in this repo's secrets, phi and code-similarity scans.
Keep at minimum:
- A changed paragraph → a tracked revision present in the output, verified by reading the XML rather than by the file differing.
- An unchanged document → output carries no spurious revisions.
- No published DOCX on
gh-pages → stated skip, not a silent pass-through.
python-docx unavailable → error, not a copied file. This is the keep-if-trimmed case: it is the only one where the current behaviour actively misinforms a reviewer.
Ordering
After #760. Independent of #761, so the two can proceed in either order once the substrate lands — but not concurrently, since both edit preview/action.yml's input block.
Worth confirming before starting: that win's tracked-changes output actually opens cleanly in Word and shows revisions as expected. The script builds revision XML by hand via OxmlElement/qn, which is the kind of thing that can produce a file Word silently repairs. Verify with a real document rather than trusting the code path.
Posted by Claude Code (AI agent) --- not written by a human.
Child of #256. Depends on #760 (the changed-chapter substrate). See the reversal comment.
Why this one is the highest-value of the three
ucdavis/win/.github/scripts/create-docx-tracked-changes.py(8.6 KB) compares the PR's DOCX output against the published DOCX ongh-pagesand produces a version carrying Word tracked changes.That is the feature that lets a co-author who does not use GitHub review a pull request. They open a Word document, see tracked changes, and comment — no branch, no diff, no PR UI. For a lab writing manuscripts in Quarto with collaborators who review in Word, this is the single most useful thing in the set.
Proposed input on
preview:docx-tracked-changes(boolean, defaultfalse). Requires the caller to be rendering DOCX at all, so it composes with #758'sformatswork.The one new dependency
python-docx, imported lazily insidecreate_docx_with_tracked_changes(create-docx-tracked-changes.py:55-58) with a warning-and-continue fallback at:136.That fallback is the thing to remove. A missing
python-docxcurrently degrades to copying the new DOCX unchanged (:62) — so the output is a document with no tracked changes that is indistinguishable from a document where nothing changed. A reviewer would read "no edits" from a dependency failure. Undershared/principles/fail-fast.mdthat must be a stated error, and the composite should install the dependency rather than hoping for it.Rewrite, not copy
3
check=Falseand 2 broadexcept. Beyond the dependency fallback:checkout_base_docxdefaultstarget_dir='/tmp/base-docx'— useRUNNER_TEMP; a fixed path collides between concurrent jobs on a self-hosted runner.git fetch origin gh-pages:gh-pageswithcheck=False(:18-19) — same silent-empty-result problem preview: port changed-chapter detection from ucdavis/win as the shared substrate for rendered-output diffing #760 describes.git ls-treeresult is filtered to.docxwith no check that any were found; zero DOCX files ongh-pagesshould say so.Tests
python-docxis a real dependency, so unit-test the diff/annotate logic directly against generated.docxfixtures built at runtime — do not commit binary fixtures, which would land in this repo'ssecrets,phiandcode-similarityscans.Keep at minimum:
gh-pages→ stated skip, not a silent pass-through.python-docxunavailable → error, not a copied file. This is the keep-if-trimmed case: it is the only one where the current behaviour actively misinforms a reviewer.Ordering
After #760. Independent of #761, so the two can proceed in either order once the substrate lands — but not concurrently, since both edit
preview/action.yml's input block.Worth confirming before starting: that win's tracked-changes output actually opens cleanly in Word and shows revisions as expected. The script builds revision XML by hand via
OxmlElement/qn, which is the kind of thing that can produce a file Word silently repairs. Verify with a real document rather than trusting the code path.Posted by Claude Code (AI agent) --- not written by a human.