Restore and document the nvda-mathcat asset update pipeline #20716

Related issues, PRs or discussions

• Integrate MathCAT into NVDA #18323 integrated MathCAT into NVDA.
• Added nvda-mathcat submodule #18610 introduced the nvda-mathcat submodule for assets fetched from MathCAT releases.
• Workflow updates nvda-mathcat#1 added the asset-fetching workflow.
• Update REQUIRED_ASSETS for 64-bit version nvda-mathcat#4 updated the required native library asset.
• Bump nvda-mathcat #19960 is the most recent manual submodule bump.
• Fetch Assets workflow
• The NVDA integration discussion notes that the PR stage was broken.
• GitHub documentation on automatic disabling of scheduled workflows

What is the current state of the codebase?

NVDA packages MathCAT's rule files and libmathcat_py.pyd through the include/nvda-mathcat submodule.

The Fetch Assets workflow in that repository is intended to run weekly. It downloads Rules.zip and the Python 3.13 64-bit Windows library from the latest MathCATForPython release, commits them to nvda-mathcat, and then opens a PR to bump the submodule in NVDA.

The workflow is currently reported by GitHub as disabled_inactivity. It has 32 recorded runs: 31 ended in failure and one in startup_failure; none completed successfully. A maintainer also noted during the original integration that the part which creates the NVDA PR was broken.

The workflow commits assets before attempting to update the NVDA submodule, so a failure in the later stage can leave nvda-mathcat updated without advancing NVDA's submodule pointer.

The nvda-mathcat README only describes the weekly asset fetch. It still names the old 32-bit Python 3.11 asset and does not document the NVDA PR stage, recovery after a failed run, or a manual update and verification procedure.

Why are changes required?

Without a working update path, fixes, language rules, and other upstream MathCAT changes do not reliably reach NVDA's built-in MathCAT. Updating the assets or bumping the submodule manually is easy to miss, and partial updates make it harder to establish which MathCAT release NVDA contains.

This is particularly visible for rule-only updates such as translations: the upstream rules may be complete and tested, while NVDA continues to ship an older rule set until someone notices and performs both repository updates manually.

A documented fallback is also needed so contributors without access to NV Access repository secrets can prepare a correct update PR and maintainers can recover the automation consistently.

What technical changes are required?

The exact implementation can be decided by the maintainers, but the update path should:

• Restore an automated sync from a MathCATForPython release to nvda-mathcat, followed by an NVDA submodule-bump PR.
• Use a durable trigger. Re-enabling the current schedule alone will allow GitHub to disable it again after another period of repository inactivity. Running the check from an active repository or triggering it from an upstream release are possible approaches.
• Repair and verify the authentication, fork/branch, and PR creation steps using least-privilege credentials. Re-running the workflow should not create duplicate branches or PRs.
• Treat Rules.zip and libmathcat_py.pyd as one release unit and record enough provenance to identify the source release.
• Validate the required assets, expected Python version and architecture, rule directory layout, and a minimal MathCAT import/speech operation before proposing the NVDA bump.
• Make the asset-sync and NVDA-PR stages separately observable and retryable so that a failure after the asset commit can be recovered.
• Update the nvda-mathcat README with the current asset names, workflow ownership, manual update procedure, submodule-bump procedure, recovery steps, and verification checklist.
• Re-enable and manually dispatch the workflow once the fixes are in place, then confirm that it either opens the expected NVDA PR or exits successfully when there is no update.

Are the proposed technical changes API breaking?

No.

Are there potential risks or issues with the proposed implementation?

The workflow downloads and distributes an upstream native binary, so release provenance and validation should remain visible in the resulting PR rather than making updates opaque or automatically merging them.

Cross-repository credentials can push to a fork and open PRs, so their scope, expiry, and ownership need to be documented and kept to the minimum required permissions.

Rules and the native library must not be updated independently. A failed or partially retried run should not produce a mixed release. The trigger also needs monitoring or a design that is not silently disabled when nvda-mathcat has no commits for an extended period.