Upstream development

This page collects rules that apply only when working inside the kdeldycke/repomatic source repository itself. Repos that use the repomatic CLI through reusable workflows do not need to follow these rules.

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 references in docs/install.md: The --version examples and example workflow @vX.Y.Z reference must reflect the latest released version.

  • Workflow job descriptions in docs/workflows.md: Each .github/workflows/*.yaml workflow section must document all jobs by their actual job ID, with accurate descriptions of what they do, their requirements, and skip conditions.

  • PAT permissions: REQUIRED_PAT_PERMISSIONS in repomatic/github/token.py is the single source of truth. When changing permissions, update all consumers: the constant and module docstring, the permission table and pre-filled URL in repomatic/templates/setup-guide.md, PAT check functions in repomatic/lint_repo.py, the lint-repo CLI docstring in repomatic/cli.py, and the lint-repo job description in docs/workflows.md.

  • Repository configuration expectations: The lint-repo job enforces repo settings described in the setup guide. When adding new setup steps, add a corresponding check to run_repo_lint() in repomatic/lint_repo.py. 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, review REQUIRED_PAT_PERMISSIONS to verify the permission set is still minimal and complete. Check secrets.REPOMATIC_PAT references across all workflow files to audit actual usage.

Auto-generated docs (no manual sync needed):

  • CLI parameters in docs/cli.md: rendered live from Click via .. click:: directives.

  • Configuration table in docs/configuration.md: regenerated by docs_update.py from Config dataclass docstrings.

  • Binary download URLs in docs/install.md: automatically frozen during releases.

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 first native_config_files path in CWD and cleaned up after invocation.

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.