Adding a new hook

Guidance for extending a2c-pre-commit-hooks without restructuring the repository.

Naming

• Hook ids are short (check-changelog, not a2c-check-changelog); the repository name is the namespace.
• Console script names match hook ids where possible (kebab-case in pyproject.toml entry points).

Implementation checklist

1. Pure logic — add a module under src/a2c_pre_commit_hooks/ with testable functions (no subprocess in core logic).

2. CLI wrapper — add src/a2c_pre_commit_hooks/hooks/<hook_name>.py with main() returning exit code 0 / 1.

3. Entry point — register in pyproject.toml:

   [project.scripts]
   my-new-hook = "a2c_pre_commit_hooks.hooks.my_new_hook:main"

4. Hook catalog — append to .pre-commit-hooks.yaml:

   - id: my-new-hook
     name: Human-readable name
     description: One-line summary for pre-commit.com
     entry: my-new-hook
     language: python
     pass_filenames: false   # or true with files:/types: as needed

5. Tests — add tests/test_my_new_hook.py covering success and failure paths; mock git I/O.

6. Documentation — update README.md hook table, docs/usage.md, and CHANGELOG.md [Unreleased].

7. Dogfood — optionally add the hook to .pre-commit-config.yaml (local repo or after tag).

Optional PyPI dependencies (example: validate)

When a hook needs an external package only for that hook, add a [project.optional-dependencies] extra and reference it from .pre-commit-hooks.yaml:

[project.optional-dependencies]
validate = ["a2c-cli==0.2.1"]

- id: validate
  additional_dependencies:
    - ".[validate]"

Do not put hook-specific deps in top-level [project.dependencies] — that would install them for check-changelog-only consumers too.

File layout example

src/a2c_pre_commit_hooks/
├── my_policy.py              # pure logic
└── hooks/
    └── my_new_hook.py        # argparse + main()
tests/
└── test_my_new_hook.py

Versioning new hooks

• Patch — bug fix or message tweak to existing hook
• Minor — new hook or backward-compatible behavior extension
• Major — breaking change to hook arguments or failure semantics consumers rely on

Document behavior changes in CHANGELOG.md so consuming repos can pin rev confidently.

Consumer impact

New hooks are opt-in: existing .pre-commit-config.yaml files list explicit hook ids. Adding a hook here does not affect consumers until they add the id under hooks:.

Review bar

Before merge:

• Unit tests pass (pytest)
• Ruff clean
• Hook entry in .pre-commit-hooks.yaml matches pyproject.toml script name
• Usage docs include copy-paste .pre-commit-config.yaml snippet
• CHANGELOG.md updated when the change is release-relevant