Development and releases
Development environment
For package installation and usage, start with getting started.
This section is for contributors working on the source. The core supports Python
3.6+, while development and documentation use the Python pinned in .python-version.
git clone https://github.com/joongi007/mathml2docx.git
cd mathml2docx
git switch develop
uv sync --locked --extra latex --extra markdown --extra test --group docs --group examples
uv run --no-sync python -m pytest -q
uv run --no-sync python -m unittest tests.test_docx_oracles -v
uv run --no-sync python -m examples.run_all
uv run --no-sync python scripts/build_docs.py
uv build
uv run --no-sync python scripts/check_dist.py
uv run --no-sync twine check dist/*
uv run --no-sync python scripts/check_wheel_install.py
Use uv 0.13.7+. pyproject.toml is the dependency source of truth; uv.lock records
interpreter-specific resolution. Run uv lock after dependency/version changes.
There is no duplicate requirements.txt configuration.
The documentation build runs the examples and records their HTML/MathML inputs for sandboxed browser previews. Existing-document examples show input fragments, not a reconstruction of their Word templates. Reference PDFs are exported with LibreOffice; regenerate them with the validation tools after changing an example's output. The docs-only pypdfium2 dependency renders every PDF page for browsers without an embedded PDF viewer. Generated preview HTML, page images and DOCX are build artifacts.
[project.dependencies]: runtime requirements.[project.optional-dependencies]: LaTeX, Markdown, and test extras.[dependency-groups]: development, docs, and example tools, not forced on users.[tool.uv.dependency-groups]: tool groups require Python 3.10+.
Release metadata tooling uses Python 3.11+; the workflow explicitly runs it on 3.14. Its tests are skipped on older runtime interpreters without excluding conversion tests.
Python 3.6 compatibility
Dependency ranges permit compatible historical releases. Python 3.6 selects python-docx 0.8.11 and older CSS/LaTeX dependencies; recent Python can use newer ones. HTML/MathML supports Python 3.6.0+. Optional LaTeX requires Python 3.6.2+ and latex2mathml 3.64+. An early 3.6.0/3.6.1 LaTeX request reports that requirement.
The build backend is flit_core>=3.11,<4. Its 3.12 series supports Python 3.6/3.7
and the current metadata/license fields, so both wheel and source installs work.
Older python-docx omits hyperlink text from paragraph.text, but the saved XML
still contains the link and text; tests inspect XML and reopen documents.
bash scripts/test_legacy.sh
bash scripts/test_legacy.sh python:3.7.17-slim-bullseye
These Docker checks copy source into a temporary directory, install it, run all
runtime tests and 11 utility doctests, build a wheel, and install that wheel into a
clean venv. A smoke check runs outside the checkout and exercises CSS, templates,
equations, Markdown, saving, and reopening. Legacy pip is >=21.3,<22.
uv sync --locked --no-default-groups --python 3.8 --extra latex --extra markdown --extra test
uv run --no-sync --no-default-groups --python 3.8 python -m unittest discover -v
Use a separate environment or --python when switching versions: the default
development interpreter is 3.14. CI covers each minor from 3.6 to 3.14; 3.6/3.7 use
Docker and modern versions use uv. Windows 3.8/3.14 and macOS 26 Arm64 with Python
3.14 are also checked.
uv support for an old interpreter does not imply it can download a Python 3.6
binary; the legacy check uses an explicit container image.
Branch workflow
master is the release branch. Start everyday work from develop:
git switch develop
git pull --ff-only
git switch -c feature/table-layout
# Commit, test, and open a PR targeting develop.
Use a branch such as release/1.0.3 from develop for stabilization if useful. Merge the release
branch into master when ready to exercise TestPyPI, and bring final fixes back to
develop. A release branch is optional for a small release; develop can target
master directly. No packages are uploaded by develop/feature PRs or pushes.
| Event | Checks/build | Upload |
|---|---|---|
| Push to develop; PR targeting develop/master | Python 3.6–3.14, quality, docs, packaging checks | None |
| Push/merge to master | Same full suite, unique candidate build, clean wheel check | TestPyPI; then installation checks from that index |
Push a final tag vX.Y.Z on a verified master commit |
Version/source gate, exact-commit TestPyPI success, full tests, final distribution/install checks | PyPI through pypi |
| Publish GitHub Release notes for an existing tag | No additional package upload | None |
Manual TestPyPI candidate on master |
Same candidate pipeline | TestPyPI and installation checks |
Manual Publish to PyPI |
Checks and build | None |
Master's package checks run inside TestPyPI candidate using the reusable Python
workflow. They are not launched a second time as a standalone push workflow.
The separate Documentation workflow builds both locales and deploys only master.
Superseded develop and pull-request checks are cancelled when a newer run starts.
Candidate and final publication workflows keep their queueing policy.
Automatic TestPyPI installation check
Master stores the intended final version, for example 1.0.0. The temporary CI
checkout receives 1.0.0.dev<run_id><attempt padded to 3 digits> in both version
fields and regenerates its lockfile. This does not commit a version bump.
Each run and full retry has a different candidate version, avoiding same-version
upload collisions. The workflow summary shows the exact published candidate.
After upload, Python 3.8 and 3.14 jobs obtain the version's actual TestPyPI JSON
metadata. They require the filename and SHA-256 to match the built wheel and
install its official TestPyPI download URL into a new venv. Dependencies come only
from PyPI; the two indexes are not mixed with --extra-index-url. The smoke check
runs outside the checkout and exercises CSS, MathML, LaTeX, Markdown, template
replacement, saving, and reopening. Python 3.6/3.7 source and wheel installation
are checked by the preceding Docker jobs.
A passed local-wheel check alone does not pass the TestPyPI workflow. Upload and both remote installation jobs must succeed. A short retry handles index visibility delay. A full rerun uses a new candidate version; after a partial upload failure, choose Re-run all jobs rather than repeatedly uploading the existing version.
First-time Trusted Publisher setup
Repository files do not configure account ownership, GitHub protection rules, or Trusted Publishers. Configure both existing index projects:
| Index | Owner | Repository | Workflow filename | Environment |
|---|---|---|---|---|
| TestPyPI | joongi007 |
mathml2docx |
testpypi.yml |
testpypi |
| PyPI | joongi007 |
mathml2docx |
publish.yml |
pypi |
- Open each project's Manage → Publishing → Add a new publisher and register the row above. TestPyPI has its own account and project permissions.
- Configure GitHub Settings → Environments → testpypi / pypi.
- To automate master candidates without a pause, leave required reviewers off
for
testpypiand permit the master branch. Add required reviewers topypiand permit final release tags. Naming an environment in YAML does not add approval rules. For a personal project, do not prevent self-review if you need to approve your own release. - Protect master and develop using PR reviews/required CI checks as desired;
restrict creation/deletion of
v*tags with a ruleset if needed.
Trusted Publishing uses OIDC id-token: write, not a long-lived API key in Secrets.
See publisher registration
and using a publisher.
Before this setup succeeds, candidate upload/install cannot be reported as verified.
Create a final release tag
- Complete Word inspection and review migration, validation, licensing, and the changelog. Check that README and user guides use the published package's pip installation commands, and update the release date and status before publication.
- Set both package versions to the intended stable version, update
uv.lock, test, and merge the source to master. - Wait for that exact master commit's TestPyPI candidate workflow to pass, including upload and both installation jobs. A successful run for another commit, a PR, develop, or only a local wheel does not qualify.
- Tag that commit and push the tag:
For example, for a prepared 1.0.3 release (substitute the version in
pyproject.toml; existing release tags must remain unchanged):
git switch master
git pull --ff-only
# Confirm this HEAD's complete TestPyPI candidate run is green first.
git tag -a v1.0.3 -m 'Release 1.0.3'
git push origin v1.0.3
Publish to PyPI requires the tag to match pyproject and __version__, the tagged
commit to be included in origin/master, and a successful testpypi.yml workflow
for exactly that SHA in this repository. It repeats the full suite and checks the
final wheel before uploading, subject to environment approval. GitHub Release
notes can be created afterward without causing another upload.
The workflow blocks publication from unverified tags; it cannot prevent users from creating a local Git tag. Repository tag rules govern who may push tags. A tag created before TestPyPI succeeds fails the publish gate; rerun after the verification completes. Use a new version to correct an already uploaded release. TestPyPI candidates and final PyPI releases have different version metadata and are rebuilt from the same source commit, not promoted as identical artifacts.
Hotfixes
Keep master on the release line; unfinished features stay on develop/release
branches. Choose an unused patch version; the commands below use 1.0.3 as an
example. Branch a hotfix from the current master release line:
git switch master
git pull --ff-only
git switch -c hotfix/1.0.3
# Fix, add a regression case, and update both versions plus uv.lock to 1.0.3.
# Open a PR targeting master; merge after checks.
Wait for the merged master commit's TestPyPI upload and installation checks, then
tag v1.0.3 on that commit. Merge master back into develop (or open a back-merge
PR) so the fix survives the next release. If develop already targets 1.1.0,
resolve version/lock conflicts while keeping develop's intended version.
This flow keeps a hotfix independent of unreleased features.