Upstream¶

repomatic installs, configures and runs a long list of external tools and libraries. When one of them misbehaves, the fix goes upstream where possible, and into repomatic where it cannot wait. This page tracks that relationship: code contributed back, workarounds provided, issues reported, and features declined.

A dependency that a sibling project consumes more directly is tracked on that project’s page: click-extra for Click, Cloup and python-tabulate, and meta-package-manager for Nuitka and the package managers it wraps.

Code contributed upstream¶

Pull requests authored by repomatic’s maintainer and merged into upstream projects.

`arrow`¶

#246 - Fix overzealous time truncation in span_range()

`awesome-lint`¶

repomatic lints awesome lists with it:

`gitignore.io`¶

#17 - Ignore rope files

`lychee-action`¶

`mdformat-pelican`¶

`mdformat-pyproject`¶

`mdformat-recover-urls`¶

#2 - Fix compatibility with mdformat-doc

`mdformat-simple-breaks`¶

`pipdeptree`¶

pipdeptree drew repomatic’s dependency graph until uv export --format cyclonedx1.5 replaced it:

`sphinx`¶

#13163 - Always print tracebacks in logs when Sphinx encounters an internal error

`sphinx-autodoc-typehints`¶

#687 - Show version in error tracebacks

`sphinxcontrib-mermaid`¶

#118 - Do not fail on empty class diagram generation

Upstreamed from repomatic¶

Issues found while building repomatic and resolved upstream. Where repomatic carried a workaround in the meantime, the entry says what it was and when it went away.

bump-my-version#331 - 1.1.1 broke the replace command on [[tool.bumpversion.files]] entries that do not apply. repomatic held bump-my-version at 1.1.0 until a later release fixed it.
lychee#1930 - lychee read its configuration only from its own file, so repomatic translated [tool.lychee] into that file. Since 0.24.0 (lychee#2104), lychee reads the section from pyproject.toml itself, and repomatic no longer translates it.
mdformat-myst#45 / mdformat-myst#46 - mdformat-myst depended on mdformat-frontmatter, which made it incompatible with mdformat 1.0.0. #46 replaced that dependency with mdformat-front-matters. repomatic ran mdformat-myst from its master branch, then from a fork, until a release carried the change.
mdformat-pelican#3 / mdformat-pelican#4 - mdformat-pelican and mdformat-gfm could not run together, also reported as mdformat-gfm#38. repomatic depended on a personal fork that carried the fix, then on unreleased upstream, then on the release that shipped it.
mdformat-web#5 - The HTML formatter added an extra doctype to html code blocks. repomatic ran a patched mdformat-web from June 2023 until 0.2.0 shipped the fix.
Nuitka#3879 / Nuitka#4024 - --main-entry-point crashed without a positional main program, then built a binary that failed at startup when the entry point carried the name of its package. repomatic compiled each entry point from its file path, with --python-flag=-m for a __main__.py, and skipped every src-layout project, until 4.3 fixed both.
Nuitka#3994 - A symlink inside an --include-data-dir tree shipped dangling, and crashed the macOS code signing. The tool runner staged a copy of the directory with no symlinks until 4.3, which ships the content of such a link.
Nuitka#3998 - enableCcache replaced a user-set CCACHE_SLOPPINESS with its own value. Since 4.3 Nuitka adds its value to the user’s.
Nuitka#4025 - --project refused to build over a py.typed and over a dependency’s package data, until 4.3.
tomlrt#171 - Table.section() dropped standalone comments and inline-array padding from the source document. repomatic rebuilt each section with a helper to keep them, and removed the helper once tomlrt 2.2.4 fixed the clone path.
zizmor#1664 - The template-injection audit failed on a multiline YAML block. repomatic turned the audit off until zizmor 1.23.0 fixed it, then turned it back on.

Also reported while building repomatic, and closed upstream:

Addressed by repomatic¶

Issues still open or unfixed upstream. repomatic provides the solution.

GitHub Actions¶

The reusable workflows work around a set of GitHub Actions limitations. The GitHub Actions limitations table lists each one, its status and the mechanism that addresses it.

PyPI¶

warehouse#11096 - Trusted publishing: Support for GitHub reusable workflows: the publish-pypi job stays in each repository’s own release.yaml, so the OIDC claim names the file that the repository registered as its Trusted Publisher.
warehouse#1388 - 404 for registered package with no release and warehouse#9536 - Unable to get a consistent view of existing/changed packages from the various APIs: PyPI’s JSON API answers 404 for some registered projects. repomatic does not read that 404 as proof that a package is missing.

Tool configuration in `pyproject.toml`¶

repomatic run translates a [tool.X] section into the native configuration file of a tool that cannot read pyproject.toml:

actionlint#623 - Support configuration in [tool.actionlint] section of pyproject.toml
biome#9239 (discussion)
gitleaks#2066 - Support configuration from pyproject.toml
zizmor#322 (discussion comment)
mdformat#432 - Option to specify path to configuration file and mdformat#562 - Add --config option to specify explicit configuration file path: mdformat finds its configuration only by discovery, so repomatic writes a temporary .mdformat.toml for the run and deletes it after.

Markdown formatting¶

repomatic post-processes the output of mdformat to undo two mdformat-myst rewrites, and changes one mdformat default:

mdformat-myst#21 - myst formatting directive with only 1 parameter: mdformat-myst turns :key: value directive options into a YAML block. repomatic restores the field list. The open fix is mdformat-myst#49.
mdformat-myst#13 - colon fence syntax is broken by escape character: mdformat-myst escapes :::{name} colon fences. repomatic removes the escape. The open fixes are mdformat-myst#36 and mdformat-myst#48.
mdformat#312 - Needless URL encoding of link destinations: repomatic turns off URL validation and bundles mdformat-recover-urls, which decodes percent-encoded non-ASCII characters back.

Awesome lists¶

mdformat-toc#17 - Feature request: ignore specific Headings / mdformat-toc#20: mdformat-toc cannot leave a heading out of the table of contents, and awesome-lint forbids some entries there. The fix-awesome-toc command deletes them.

Python formatting¶

ruff#7414 - Formatter: wrap comments (E501): Ruff does not wrap long comments. The format-python job also runs autopep8, limited to that one fix.

Shell formatting¶

sh#1203 - zsh: support inline loop syntax: shfmt cannot parse some Zsh constructs, so repomatic keeps Zsh files away from it.

Workflow linting¶

actionlint#711 - Support the new $/ self-repository uses: syntax / actionlint#732: actionlint rejects the $/ self-repository syntax of GitHub. repomatic’s workflows call their own reusable workflows through workspace-relative ./ paths instead.

Test matrix¶

uv#12906 - uv installs x86_64 Python on arm64 Windows: tests.yaml forces a native ARM64 interpreter on the Windows ARM64 runner, which would otherwise test an emulated x86_64 Python. uv 0.13.0 prefers the native interpreter (uv#22100), and the workflows pin an older uv.
Todo

When sync-workflow-pins moves the uv pin of the setup-uv steps to 0.13.0 or later:
- Delete the Force native ARM64 Python on Windows ARM64 step of tests.yaml, and the UV_PYTHON fallback in the Install Python step after it.
- Rewrite the validate-arch comment of tests.yaml that says uv prefers an x86_64 interpreter on aarch64.
- Build the two Windows binaries with --managed-python in a canary run of _release-engine.yaml. If both pass verify-binary and the self-tests, pass the flag on every platform.
- Delete this entry, and the example that names the step in the repomatic-audit skill.
When a Python version has no native build, uv 0.13.0 falls back to x86_64 with no error. The explicit request of the step fails there. Python 3.10 has none, and the test matrix already excludes it on windows-11-arm.

Nuitka binary builds¶

Nuitka integration details the workaround for each of these:

Nuitka#3909 - With --project the [tool.nuitka] section of pyproject.toml is ignored: since 4.2 Nuitka reads [tool.nuitka], but only under --project, a mode repomatic cannot use, so the tool runner turns the section into command-line flags. Nuitka#2136 asked for the same support earlier.
Nuitka#3996 - ccache never hits across CI machines: the tool runner installs Nuitka into the project virtualenv, whose path is the same on every runner. The release workflow also writes base_dir into ccache.conf.
Nuitka#3997 - Tool downloads are fetched and executed without integrity verification: the macOS builds turn ccache off, which keeps its unverified download out of the build.

Dependency cooldowns¶

uv#20995 - Allow sharing exclude-newer-package across workspaces: file reference, env var, or repo-level config: uv has no configuration or environment knob for --exclude-newer-package, so repomatic adds the exemption to every frozen command line. Glob exemptions (uv#20788) or pin-based bypasses (uv#19864, uv#18921) would also remove the need.
uv#18792 - Prune stale exclude-newer-package entries on uv lock: repomatic removes the stale entries itself after it relocks.

Dependency graph¶

mermaid#4182 - click cannot be used for node IDs: a Mermaid keyword breaks a graph when used as a node ID. repomatic keeps keywords out of the node IDs of its dependency graph, as pipdeptree#201 does upstream.

Dependency choices¶

Two dependencies stand in for a feature that a preferred library lacks:

whenever#277 (discussion): whenever has no humanizer, so repomatic uses arrow for its human-readable times.
wcmatch#226 - Possibly add a gitignore parser: wcmatch cannot read .gitignore files, so repomatic also depends on py-walk.

Issue reporting¶

create-issue-from-file#298 - Avoid creating duplicate issues: the action opens a new issue on every run. repomatic manages the issues its jobs open, so a new run does not duplicate them.

Documentation¶

furo#921 (discussion): Furo shows no icons in toctree entries. repomatic’s documentation adds them with CSS.

Declined by upstream¶

Pull requests and features that upstream maintainers rejected.

mypy#13294 - Auto-detect minimal Python for --python-version option: repomatic derives --python-version from requires-python when it runs mypy.
pyupgrade#688 - Auto-detect minimal Python version: repomatic computed the minimal Python version from requires-python while it still ran pyupgrade.
sh#1268 - Support configuration in [tool.shfmt] section of pyproject.toml: shfmt reads its style from .editorconfig only, so repomatic has no [tool.shfmt] section.

Open upstream¶

Pull requests and issues still pending upstream.

awesome-lint#229 - Fix false positives in balanced-punctuation
bump-my-version#146 - Non-matching glob patterns don’t raise FileNotFoundError
coveragepy#2330 - feat: name the data file in the Can't combine error: coverage combine stops on a mix of branch and statement data, and its error names no data file. The lowest-direct cell of tests.yaml hit it: pytest-cov 4.0.0 measured a child interpreter that a test started in another directory. That test now removes the COV_CORE_* and COVERAGE_* variables from the environment of its child.
lychee#2249 - Recognize {#id} heading anchors in --include-fragments: closed by lychee#2250, which no stable release carries yet.
lychee#1772 - Suggest alternative frontend services from LibRedirect
markdown-it-py#445 - Image alt text loses backslash escapes and entities: the cause of mdformat#599 and MyST-Parser#1210.
mdformat#599 - Backslash escapes and entities are deleted from image alt text: the format-markdown job applies that loss to every image it formats. See A known mdformat defect.

Todo

When a markdown-it-py release carries the fix for executablebooks/markdown-it-py#445, run the reproducer from hukkin/mdformat#599 through repomatic run mdformat. Then update this entry and A known mdformat defect to match the result.
mdformat-myst#25 - Block attributes formatting introduce extra empty line
mdformat-web#8 - format_xml drops comments and the XML declaration: since 0.2.0, formatting an xml code block deletes its comments and its <?xml ...?> declaration. repomatic pins mdformat-web 0.2.0, so the format-markdown job applies that loss to every xml block it formats.

Todo

When sync-tool-versions moves the mdformat-web pin past 0.2.0, run the reproducer from hukkin/mdformat-web#8 through repomatic run mdformat. Then update this entry to match the result.
MyST-Parser#1210 - Image alt text loses backslash escapes: the same loss in the alt attribute of a page that Sphinx builds.
MyST-Parser#1151 - Cross-reference to an explicit target emits a false-positive myst.xref_missing warning
Nuitka#4087 - One new local variable makes every C file miss ccache since 4.3: the canary build misses every file after a commit that adds or removes one frame type description. See Compile caching.

Todo

When a Nuitka release carries the fix for Nuitka/Nuitka#4087, add it to the matrix of the ccache-type-description.yaml workflow in kdeldycke/nuitka-test, and run it. Then update this entry and Compile caching to match the result.
py-walk#11 - py-walk maintenance status: sly, the only dependency of py-walk, is retired, and py-walk has had no commit since 2024-10-26. repomatic reads .gitignore through py-walk: see repomatic.file_inventory.
py-walk#10 - fix: read the pattern file as UTF-8 instead of the locale encoding: get_parser_from_file decodes the pattern file with the locale encoding. repomatic decodes .gitignore itself until a release carries the fix: see repomatic.file_inventory.
ruff#19421 - Failure to create cache key on invalid symlink
sphinx#14623 - todolist produce duplicate titles for admonitions
sphinx-design#304 - Implements vertical tabs

typos#998 - False positive: hda → had