This hook is responsible for standardizing and synchronizing the developer environment of repositories by the ComPWA organization. Coding conventions are enforced through automated checks instead of through a contribution guide. These conventions have to be regularly updated across all repositories as developer tools introduce new features and deprecate old ones.
The check-dev-files hook can also be used as a cookie cutter for new repositories by adding the following to your .pre-commit-config.yaml file:
repos:-repo:https://github.com/ComPWA/policyrev:""hooks:-id:check-dev-filesargs:---repo-name="short name for your repository"
The checks are also exposed through a short Typer-based policy command. Running policy without a subcommand runs every check at once, which is exactly what the check-dev-files pre-commit hook does. The subcommands group the checks by domain, so you can run just a subset.
You do not need to install anything: with uv, uvx fetches and runs the command on the fly. For example, to see which subcommands are available:
uvx caches the Git checkout, so add --refresh directly after uvx to pull the latest commit from the default branch.
If you run the command often, you can install it as a persistent tool with uvtoolinstall (or pipxinstall) and call policy directly, updating it with uvtoolupgrade--reinstallcompwa-policy. When the pwa command is installed alongside this package, the same command is also available as pwapolicy... through a pwa.commands entry point.
The check-dev-files hook (and the policy command without a subcommand) only accepts the options that are shared across the whole repository, such as --repo-name. These can be added to the args key in your .pre-commit-config.yaml file. Options scoped to a single area (e.g. --no-pypi) are exposed on the matching subcommand instead and are configured through its [tool.compwa.policy.<group>] table (see below). The full command tree and its options are:
Instead of repeating the same flags under args: in every .pre-commit-config.yaml, a repository can declare its options once in a [tool.compwa.policy] table in its pyproject.toml. Each option is resolved with the following precedence (first match wins):
the option explicitly passed on the command line (e.g. under args:);
the [tool.compwa.policy] table in pyproject.toml;
the built-in default.
The table is organized hierarchically, mirroring the subcommand tree: options shared by several checks live in the top-level table, while options that belong to a single subcommand live in a sub-table named after it. The env subcommand maps to a setup table, and environment variables are a plain nested table under [tool.compwa.policy.setup.env]:
[tool.compwa.policy]# options shared by several checksdev-python-version="3.13"package-manager="pixi"[tool.compwa.policy.python]imports-on-top=truetype-checker=["mypy","pyright"][tool.compwa.policy.nb]no-binder=trueallowed-cell-metadata=["scrolled"]# options of the `env` subcommand (uv, conda, pixi, direnv)[tool.compwa.policy.setup]keep-contributing-md=true# environment variables, as a plain TOML table[tool.compwa.policy.setup.env]PYTHONHASHSEED="0"[tool.compwa.policy.repo]gitpod=true
Both the native TOML form (arrays, tables, booleans) and the legacy command-line string form ("mypy,pyright", "A=1,B=2") are accepted, so an existing args: list can be moved into pyproject.toml verbatim.
Some policy updates introduce breaking changes to a repository’s configuration. The check-dev-files pre-commit hook cannot rewrite your files to apply such a change itself — it can only detect it and fail. The policymigrate command applies these migrations for you, but because it modifies configuration files it has to be run outside of pre-commit, as a one-off command.
Important
If the check-dev-files hook starts failing after an upgrade, run policymigrate to bring your configuration up to date. You do not need to install anything first:
