Skip to content

[Feat] Conventional Commits breaking-change marker (feat!: / feat(scope)!:) #23

@atlas-apex

Description

@atlas-apex

Context

Rex's review of #17 flagged that the commit-format regex and the PR-title regex in `git-conventions.md` both reject `feat!: breaking change` (the Conventional Commits 1.0 breaking-change marker). This is consistent between the hook and the existing convention, so it's not a bug — but Conventional Commits compliance is a common ask and the exclamation-mark marker is how most teams indicate breaking changes.

Design question

Do we want to support the Conventional Commits 1.0 breaking-change marker across the two hooks + the rule file?

Pro: industry-standard notation, some tools (semantic-release, commitlint, changelog generators) expect it.

Con: adds complexity, the existing `BREAKING CHANGE:` footer convention already handles the semantic need, and we'd have to decide whether to hard-block on missing `BREAKING CHANGE:` footer when `!` is present (Conventional Commits spec says it's optional when `!` is used).

Acceptance Criteria (if we decide to support it)

  • Extend the type regex to `^(feat|fix|...)(\([^)]+\))?!?:[[:space:]]+.+` in both:
    • `.claude/hooks/validate-commit-format.sh`
    • `.claude/hooks/validate-pr-create.sh` (the title-format check)
    • `.claude/rules/git-conventions.md` (the stated regex)
  • Decision: when `!` is present, do we require a `BREAKING CHANGE:` footer in the commit body? Either:
    • (a) Yes (stricter) — add a verify-breaking-change-footer.sh hook that blocks commits with `!` but no footer.
    • (b) No (looser) — trust the `!` alone as the marker. Matches spec.
  • Write a short AgDR recording the `!` support decision and the footer-requirement decision.
  • Smoke test: `feat!: breaking subject` is now accepted; `feat(api)!: breaking API change` is accepted.

Non-goals

  • Does NOT automate changelog generation from breaking-change markers.
  • Does NOT integrate with semantic-release.

Links

Metadata

Metadata

Assignees

Labels

P3Low — ergonomics, nice-to-have

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions