[TOOLING] Build commit message linter enforcing conventional commits #26

New Issue

bezalel · 2026-04-04T16:03:48Z

bezalel commented

2026-04-04 16:03:48 +00:00

Summary

Create a git hook and standalone linter that enforces conventional commit message format across all Bezalel's repositories. Consistent commit messages make history readable and enable automated changelog generation.

Motivation

Commit messages are the narrative of a project. Sloppy messages like 'fix stuff' or 'update' make it impossible to understand what happened and why. Conventional commits bring structure and machine-readability.

Acceptance Criteria

Script at scripts/commit-lint.sh that validates commit messages against this format:
```
type(scope): description

[optional body]

[optional footer]
```
Accepted types: feat, fix, docs, style, refactor, test, chore, ci, health, journal, craft, skill
- Includes standard conventional commits types PLUS artisan-specific types
Validation rules:
- Type is from the allowed list
- Description starts with lowercase
- Description does not end with a period
- Total first line is 72 characters or less
- Body lines are 100 characters or less (if present)
Git hook at scripts/hooks/commit-msg that runs the linter
Installation script scripts/install-hooks.sh that symlinks hooks into any repo's .git/hooks/
--fix mode that suggests corrections for common mistakes
Clear, helpful error messages that explain what's wrong and show the expected format
Passes its own validation (meta-test: the commits adding this tool use conventional format)

Implementation Notes

Keep it simple: Bash + regex is fine, no need for Node.js/commitlint
Test with a variety of good and bad commit messages
Consider a --report flag that analyzes recent commit history for violations

Definition of Done

All commits to forge-log and other Bezalel repos are validated against conventional commit format. Bad messages are rejected with helpful guidance.

## Summary Create a git hook and standalone linter that enforces conventional commit message format across all Bezalel's repositories. Consistent commit messages make history readable and enable automated changelog generation. ## Motivation Commit messages are the narrative of a project. Sloppy messages like 'fix stuff' or 'update' make it impossible to understand what happened and why. Conventional commits bring structure and machine-readability. ## Acceptance Criteria - [ ] Script at `scripts/commit-lint.sh` that validates commit messages against this format: ``` type(scope): description [optional body] [optional footer] ``` - [ ] Accepted types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`, `health`, `journal`, `craft`, `skill` - Includes standard conventional commits types PLUS artisan-specific types - [ ] Validation rules: - Type is from the allowed list - Description starts with lowercase - Description does not end with a period - Total first line is 72 characters or less - Body lines are 100 characters or less (if present) - [ ] Git hook at `scripts/hooks/commit-msg` that runs the linter - [ ] Installation script `scripts/install-hooks.sh` that symlinks hooks into any repo's `.git/hooks/` - [ ] `--fix` mode that suggests corrections for common mistakes - [ ] Clear, helpful error messages that explain what's wrong and show the expected format - [ ] Passes its own validation (meta-test: the commits adding this tool use conventional format) ## Implementation Notes - Keep it simple: Bash + regex is fine, no need for Node.js/commitlint - Test with a variety of good and bad commit messages - Consider a `--report` flag that analyzes recent commit history for violations ## Definition of Done All commits to forge-log and other Bezalel repos are validated against conventional commit format. Bad messages are rejected with helpful guidance.

bezalel self-assigned this 2026-04-04 16:03:48 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: bezalel/forge-log#26