Skip to content

adding-a-hook.md

Latest commit

 

History

History
47 lines (40 loc) · 2.06 KB

adding-a-hook.md

File metadata and controls

47 lines (40 loc) · 2.06 KB

Adding a hook

Use this checklist when adding a hook. The repo has three categories; pick the one that matches your tool and copy the closest existing hook as a starting point.

Decide the category

  • Static binary download — upstream ships per-platform release binaries. Start from hooks/_template/. Reference: hooks/shfmt/.
  • Toolchain wrapper — tool ships with a language runtime the project already requires. Reference: hooks/gleam-format/.
  • JVM JAR — distributed as a JAR on Maven Central or a GitHub release. Reference: hooks/ktfmt/.

Checklist

  1. Create hooks/<id>/ with:
    • run.sh (executable, set -euo pipefail, sources lib/platform.sh, lib/download.sh, and/or lib/jvm.sh as appropriate).
    • version.txt (single line, just the version, e.g. 0.51).
    • checksums.txt for category 1/3 — one line per (os, arch) asset.
    • README.md describing the hook.
    • tests/ok.<ext> and tests/bad.<ext> fixtures.
  2. chmod +x hooks/<id>/run.sh.
  3. Add an entry to .pre-commit-hooks.yaml with id, name, description, entry: hooks/<id>/run.sh, language: script, file/type matchers, and default args.
  4. Add a pytest module tests/test_<id>.py covering at minimum:
    • success: hook exits 0 against tests/ok.<ext>.
    • failure: hook exits non-zero against tests/bad.<ext>.
    • idempotency: running against an already-formatted file leaves it untouched (where applicable).
  5. Add a row to the hook table in README.md (move from "planned" to "stable" when shipped).
  6. Add a ## [Unreleased] bullet in CHANGELOG.md.
  7. Add a per-hook page under docs/hooks/<id>.md.
  8. Run task lint && task test.
  9. Verify prek try-repo . <id> --all-files works locally.

Checksums

  • For category 1/3 hooks, populate real sha256 values from the upstream release page in the same PR that introduces the hook. Do not ship a hook with placeholder zeros — download_tool refuses to use them.
  • Renovate bumps version.txt automatically. The release engineer updates checksums.txt in the same PR.