Todo list¶
Every pending item this project tracks, collected from the {todo} admonitions left in the documentation pages and in the docstrings autodoc renders. Each entry links back to where it is written, which is next to the code or the prose it acts on.
Most wait on an upstream release: the ticket named in an item is what closes it.
Todo
Once the docs group requires a click-extra release newer than 10.2.0, one
whose prep_path returns a replaced sys.stdout as-is, drop
click_extra_run_capture from docs/conf.py. Once the runtime floor reaches
that release too, reword the paragraph above: - then returns the live
sys.stdout whenever something replaced it.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/github/outputs.py:docstring of repomatic.github.outputs.write_text_output, line 7.)
Todo
Swap the two reusable-workflow lanes in release.yaml to GitHub’s $/
self-repository syntax, and drop their suppression, once actionlint accepts
the form: it rejects $/ as a malformed ref today, per
rhysd/actionlint#711 and
rhysd/actionlint#732. The
publish-pypi step keeps ./ either way, since $/ resolves against the
workflow’s own commit rather than the release commit it checks out.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/github/workflow_sync.py:docstring of repomatic.github.workflow_sync, line 27.)
Todo
Drop the py-walk dependency and parse .gitignore with wcmatch, already
imported here for globbing, once it reads gitignore files natively:
facelessuser/wcmatch#226.
Pick another parser first if
pacha/py-walk#11 ends with
py-walk retired: sly, its only dependency, already is.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/file_inventory.py:docstring of repomatic.file_inventory, line 14.)
Todo
Stop excluding Zsh once shfmt formats those constructs:
mvdan/sh#1203. Give the
shellcheck registry entry a file list of its own in the same change,
which keeps the Zsh files out.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/file_inventory.py:docstring of repomatic.file_inventory.FileInventory.shfmt_files, line 19.)
Todo
Delete this pruning pass once uv prunes stale exclude-newer-package
entries natively:
uv#18792.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/deps/cooldown.py:docstring of repomatic.deps.cooldown.UvSettings.prune, line 3.)
Todo
Delete this module once mdformat-toc can express the exclusion in the ToC
marker itself, through
hukkin/mdformat-toc#17 or
hukkin/mdformat-toc#20.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/awesome_toc.py:docstring of repomatic.awesome_toc, line 19.)
Todo
Compare the clcache keys of two builds on one image, then state what changes them.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/nuitka.md, line 116.)
Todo
Collapse the job’s two Ruff steps, check then format, into one invocation once Ruff unifies linting and formatting behind a single command: astral-sh/ruff#8232. The autopep8 step goes the same way once Ruff wraps long comments: astral-sh/ruff#7414.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/workflows.md, line 130.)
Todo
Once the Nuitka pin moves to a release carrying Nuitka/Nuitka@381a18f17, delete the ccache.conf base_dir write of prepare_compile_cache(), then move this entry to Upstreamed from repomatic. Keep the install into the project virtualenv: the fix keeps the original include paths on Windows.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream.md, line 213.)
Todo
Once MyST-Parser renders an {eval-rst} block into the page’s own document, delete this entry. The rehome_moved_nodes hook of click_extra.sphinx tracks the same release in click-extra. Keep test_pickled_pages_carry_no_build_environment in tests/test_sphinx_crossrefs.py: it shows whether the upstream change holds.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream.md, line 245.)
Todo
Once Sphinx publishes no viewcode page for an unused module under a parallel read, delete this entry. The drop_unused_viewcode_modules hook of click_extra.sphinx tracks the same fix in click-extra.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream.md, line 251.)
Todo
Once the minimum-release-age cooldown lets repomatic run mdformat resolve markdown-it-py 4.3.0, which carries the fix for executablebooks/markdown-it-py#445, run the reproducer from hukkin/mdformat#599 through it. Then update this entry and A known mdformat defect to match the result. With markdown-it-py main at 9aa1aae, which differs from 4.3.0 by its release commit alone, a bare mdformat 1.0.0 keeps every character of that reproducer: it writes \* as * and & as &, as it does in link text. A code span in the alt text makes it stop on Could not format instead: markdown-it-py now keeps the span, while mdformat’s own renderer still drops it, as hukkin/mdformat#414 tracks.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream.md, line 275.)
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.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream.md, line 283.)
Todo
Drop the [tool.X] translation layer for each tool that grows native pyproject.toml support, as lychee already has. The standing upstream requests, all still unshipped:
actionlint#623,
biome#9239,
gitleaks#2066,
zizmor#322.
The same request for shfmt (sh#1268) was declined.
Nuitka#3909 shipped in 4.2, but only for --project builds, which take their entry points from the project configuration. repomatic names one entry point per build on the command line, so the nuitka bridge stays.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/tool-runner.md, line 13.)
Todo
Build lint-prose, run by lint.yaml over Markdown, docstrings, comments and .claude/: em dashes, Latin abbreviations, the AI-writing tropes as a bundled word list, Unicode decoration, sentence length, sentence-case headings, unbackticked versions, the spelling of proper nouns like “GitHub Actions”, and the owner/repo#N link-text form. It retires about 3,000 words of prose rules. Settle the link-text rule first: it is broken in 135 places, so either the rule or the pages change before the check lands.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 42.)
Todo
Build a local gate command that runs CI’s checks in order with the pinned registry tools: formatters in verify mode against a worktree copy, a bare run mypy, lint-changelog, lint-deps, the workflow linters when a workflow changed, the typos and biome smoke runs, and a fresh uvx --from . resolution with the cooldown hint: parsed. It retires step 2 of repomatic-ship and steps 3 and 5 of babysit-ci, about 3,000 words. Its name is open: the naming table reserves the verb prefixes.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 46.)
Todo
Build lint-commits on pull request and push ranges, with --range for the gate: subject length and shape, [changelog] as the only bracket prefix, the skip-ci tokens, the body cap, a #N that resolves to a real issue, and forbidden trailers from a [tool.repomatic] list. It retires about 900 words across the commit-message rules and two skills.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 50.)
Todo
Build lint-docs for Sphinx repositories, as its own command or as lint-repo checks gated on is_sphinx: html_logo beside the logo pair, ogp_image outside _static, the exec-directives flag, a suppressed myst.xref_missing, the html_baseurl slash, uncommented suppress, nitpick and linkcheck entries, an extension missing from the docs group, a setting equal to its Sphinx default, an automodule on a guide page, bare markers, an orphan .rst and the toctree shape. It retires about 3,500 words of the sphinx-docs agent and half of sphinx-docs-sync; title-octicons is the first row built.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 54.)
Todo
Add the lint-deps warnings the review tables of repomatic-deps still describe in prose: an accreted floor comment, a weak-comment phrase, an exemption for a package no longer declared, an uncommented exemption, and a marker that contradicts its rationale. About 300 words.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 58.)
Todo
Add the lint-repo checks that the filename, uv-flag, YAML and ordering rules still state in prose: filename case and short extensions, a symlinked .gitignore, bumpversion ignore_missing_files, a CI-only flag in addopts, a bare uv run or uvx without --no-progress or --frozen outside the documented job, apt in place of apt-get, a version literal in no recognized shape, a YAML comment block over 8 lines, a stale *-probe.yaml, the awesome topics, jobs ordered by needs level, and every job id present in docs/workflows.md. About 900 words.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 62.)
Todo
Add the hygiene tests the code-style rules still state in prose: every Python comment ends with a period, no Google docstring section, a minimal __init__.py, no MyST markup in a Click command docstring, every Config field documented, the example-data denylist, and the docs/workflows.md version samples equal to the latest tag. About 250 words.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 66.)
Todo
Give six skills their mechanical half as a command or a registry entry: lint-translations for the parity checks of translation-sync, an upstream-page state audit for upstream-audit, a signal table for awesome-triage, sync-milestones for github-housekeeping, scan-virustotal --report plus the vendor templates as data for av-false-positive, init --check, the upstream-norms discovery and log-anchor resolution of file-bug-report, and resvg in the tool registry for brand-assets. About 4,000 words, one item at a time.
(The original entry is located in /home/runner/work/repomatic/repomatic/docs/upstream-development.md, line 70.)
Todo
Drop the YAML-block fixup in the mdformat post-process callback once
executablebooks/mdformat-myst#49
merges upstream. See _DIRECTIVE_YAML_OPTIONS_RE for the shape it repairs.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry, line 21.)
Todo
Drop the colon-fence fixup in the same callback once mdformat-myst ships
colon-fence support, via either
executablebooks/mdformat-myst#36
or
executablebooks/mdformat-myst#48.
See _ESCAPED_COLON_FENCE_RE for the shape it repairs.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry, line 28.)
Todo
Once lychee ships 0.25.0, the release expected to carry
lycheeverse/lychee#2250,
run the {#id} reproduction from
lycheeverse/lychee#2249
through repomatic run lychee, and report the result there, as that comment
commits to. The file:// docs-fragment entry in [tool.lychee] stays either
way: lychee reads the Markdown source, which holds neither MyST (target)=
labels nor the anchors directives generate at build time.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry, line 38.)
Todo
Move those integrity checks to __post_init__ if the registry ever becomes
user-configurable: a test only covers the specs shipped here.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry.BinarySpec, line 16.)
Todo
Move those integrity checks to __post_init__ if the registry ever becomes
user-configurable: a test only covers the specs shipped here.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry.ToolSpec, line 10.)
Todo
Give the mdformat entry a config_flag="--config" once mdformat accepts an
explicit config path, so it stops relying on discovery from the working
directory:
hukkin/mdformat#432 and
hukkin/mdformat#562.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/tooling/registry.py:docstring of repomatic.tooling.registry.TOOL_REGISTRY, line 7.)
Todo
Declare the exemption once, instead of splicing it onto every frozen command
line, as soon as uv grows a configuration or environment knob for
--exclude-newer-package:
astral-sh/uv#20995. Glob
exemptions (astral-sh/uv#20788)
and pin-based bypasses
(astral-sh/uv#19864,
astral-sh/uv#18921) could settle
it too.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/release/self_pin.py:docstring of repomatic.release.self_pin.cooldown_exemption, line 28.)
Todo
Carry the creation day as a non-accruing attribute beside commit and
release, so no star reading can collide with it, and let
repomatic.metrics.chart.render_chart() read a by-age origin from
it. This is a store schema change: it adds a metric value that every
consumer’s own store-shape test enumerates, so it lands with a note to
downstream repositories rather than silently.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/metrics/store.py:docstring of repomatic.metrics.store.Source.rank, line 24.)
Todo
Widen the JSON branch beyond an iterable of dict[str, str] and a flat
dict[str, str], the two shapes it asserts on today, when a metadata
key needs a richer one.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/metadata/output.py:docstring of repomatic.metadata.output.format_github_value, line 21.)
Todo
Review the octicon of each page against the 81 icons that sphinx-design
0.8.0 adds to the 328 of 0.7.0, through
executablebooks/sphinx-design#309,
like agent, ai-model and flowchart. Adopt a new icon only once the
docs dependencies of every site that takes it require
sphinx-design>=0.8: 0.7.0 reports an error on an icon it does not
know, and renders the role as plain text.
(The original entry is located in /home/runner/work/repomatic/repomatic/repomatic/lint_repo/site.py:docstring of repomatic.lint_repo.site.OcticonRegistry, line 8.)