Skip to content

Enforce Conventional Commits format with pre-commit hook #974

@smoparth

Description

@smoparth

Problem

CONTRIBUTING.md requires Conventional Commit format (feat:, fix:, refactor:, etc.) but there is no tooling to enforce it. Non-conforming commit messages (e.g., "fixed the thing", "wip") can be pushed without any validation, making commit history inconsistent and harder to parse for changelog generation, semantic versioning, and AI-assisted development workflows.

The .pre-commit-config.yaml already has hooks for code quality (ruff, mypy) but nothing for commit message validation.

Context

  • The project already uses .pre-commit-config.yaml with local hooks wired through hatch.
  • CONTRIBUTING.md documents the expected commit format under "Commit Guidelines".
  • AGENTS.md also references Conventional Commits as the required format for AI agents.
  • The gap is enforcement — the convention is documented but not validated.

Definition of Done

  • A commit-msg hook validates commit messages against the Conventional Commits spec
  • Non-conventional messages are rejected locally with a clear error
  • Standard types pass: feat:, fix:, refactor:, docs:, test:, chore:, ci:
  • Scoped commits pass: feat(resolver):, fix(bootstrapper):
  • Hook is installed via the existing hatch run lint:install-hooks workflow
  • Existing pre-commit hooks (ruff, mypy) are unaffected
  • CONTRIBUTING.md updated if install instructions need changes

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions