Upstream development¶
This page collects rules that apply only when working inside the kdeldycke/repomatic source repository itself.
Documentation sync¶
The following documentation artifacts must stay in sync with the code in this repository. When changing any of these, update the others:
Version samples in
docs/workflows.md: Two samples must name the latest released tag: theuses: kdeldycke/repomatic/.github/workflows/*.yaml@vX.Y.Zreference in the example-usage section, and theUpgrade repomatic to vX.Y.Zpull request title in thesync-repomaticjob description. Bump both by hand during the docs reconciliation pass. Thedocs/install.mdversion pins are covered under the auto-generated docs below.Workflow job descriptions in
docs/workflows.md: Each.github/workflows/*.yamlworkflow section must document all jobs by their actual job ID, with accurate descriptions of what they do, their requirements, and skip conditions.PAT permissions:
PAT_PERMISSION_PROBESinrepomatic/github/token.pyis the single source of truth, onePatProberow per fine-grained permission, run bycheck_all_pat_permissionsfor bothlint-repoandsetup-guide. A new probe row reaches every consumer automatically, thepat-permissionsentry oflint-repo --helpand of thelint-repojob description indocs/workflows.mdincluded: both list the permission names of the probes. When changing permissions, update the probe table and module docstring, and the permission table and pre-filled URL inrepomatic/templates/setup-guide-token.md.Repository configuration expectations: The
lint-repojob enforces repo settings described in the setup guide. When adding new setup steps, add a correspondingRepoCheckentry toREPO_CHECKSinrepomatic/lint_repo/roster.py, whichrun_repo_lint()walks. Put the check itself, a function taking theLintContextthat both commands share, in therepomatic/lint_repo/module of its subject. Give the entry asummary, whichlint-repo --helprenders with a severity that comes from the entry’sfatalflag. Give it adescriptiontoo, which thelint-repojob description indocs/workflows.mdrenders as the check’s bullet. Open the description onFailsfor a fatal check and onWarnsfor any other:tests/test_lint_repo.pyholds the two together. If the check cannot be automated, document the limitation in a comment.PAT permission review: When adding or removing workflow jobs that use
REPOMATIC_PAT, reviewPAT_PERMISSION_PROBESto verify the permission set is still minimal and complete. Checksecrets.REPOMATIC_PATreferences across all workflow files to audit actual usage.Module reference pages:
[tool.repomatic] docs.apidoc-extra-argspasses--separate, so every module gets its owndocs/{module}.mdpage.repomatic update-docswrites a missing page but never rewrites an existing one. It also lists each new page in the toctree of its package page (docs/repomatic.mdfor a top-level module,docs/repomatic.{subpackage}.mdotherwise). That wiring only adds: a module that is renamed or removed leaves its old page and toctree entry to delete by hand, and its old URL to redirect indocs/_redirects.tests/test_readme.pyfails on a module that has no page. The file inventories thattests/test_metadata.pychecks come fromgit ls-files, so an untracked file in the checkout fails them.
Auto-generated docs:
CLI parameters in
docs/cli.md: rendered live at build time from Click via the{click:tree}directive.Configuration table in
docs/configuration.md: rendered live at build time from theConfigdataclass via the{click:config}directive.Binary download URLs and
Specific versionCLI pin indocs/install.md: both version-pinned, both ratcheted forward to the new release automatically byprepare-release’sfreeze_install_download_urlsandfreeze_install_cli_version.Plugin marketplace pin in
.claude-plugin/marketplace.json, and the plugin manifest version in.claude/.claude-plugin/plugin.json:prepare-release’sfreeze_marketplace_pinwrites both the entry’srefand itsversionon the release commit.freeze_plugin_manifest_versionstamps the same version into the manifest, which is the string the Claude Code CLI compares to detect an update (see § How the pin moves). Thenunfreeze_marketplace_refreturns therefto the default branch and leaves both versions on the release. It is deliberately not a[[tool.bumpversion.files]]entry: that would rewrite the version on the post-release bump too, advertising avX.Y.Z.devNrelease that never exists.
Tool runner: flags vs config¶
When adding or modifying a tool in TOOL_REGISTRY, choose the right mechanism for each default based on whether downstream repos should be able to override it:
default_flags: operational/cosmetic flags that are always applied and not overridable: output formatting (--color), operational mode (--write-changes, --in-place), enforcement level (--strict), network policy (--offline), tool-specific quirks with no config-file equivalent.
default_config (bundled file in repomatic/data/): behavioral preferences a downstream repo might legitimately want to override via its own config: lint rule selection, formatting preferences (numbering, line length), spell-check dictionaries, tool-specific rule configuration (severity, thresholds).
The test: if a downstream repo might reasonably want the opposite setting, it belongs in a config file. CLI flags take precedence over config files in most tools, so an overridable preference in default_flags silently prevents downstream customization.
Config delivery has two paths depending on whether the tool accepts a --config flag:
Tools with
config_flag: the bundled default is passed via that flag at invocation time.Tools without
config_flag(CWD-discovery only): the bundled default is written to the firstnative_config_filespath in CWD and cleaned up after invocation. A second run of the same tool in that directory waits for the first to finish, so it never reads a config the first run is about to remove.
Instructions to mechanize¶
The bundled skills, agents and AGENTS.md carry rules that a check could enforce. The --deep instructions lane of the repomatic-ship skill turns each one into a conformance test, a lint-repo check or an autofix rule, then deletes the prose it retires. The entries below rank what is left, by the prose each one retires per effort: the ruff rule selection, wrap = "no" for mdformat, the ci-status flags, the lint-changelog ordering checks and the lint-python gate are built. A lint-repo check beats a test here: a test runs in this repository alone, a check reaches every repository that pins the release.
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.
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.
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.
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.
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.
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.
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.
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.
Release checklist¶
The release process is automated by the release.yaml workflow. See § Release engineering for the complete list (git tag, GitHub release, binaries, PyPI, changelog) and design rationale for the workflow itself, including the workflow_run checkout pitfall, immutable-release semantics, concurrency strategies, and freeze/unfreeze commit structure.
PyPI Trusted Publisher registration¶
The upstream kdeldycke/repomatic package publishes to PyPI via OIDC Trusted Publishing. The publisher is registered against the upstream’s own release.yaml workflow file: the publish-pypi job inside that file runs only on the push trigger (self-release), so its OIDC job_workflow_ref claim resolves to kdeldycke/repomatic/.github/workflows/release.yaml. Downstream repos invoking the workflow via workflow_call skip that job and run their own caller-side publish-pypi job instead, which uses the publish-pypi composite action.