Commit Convention¶

This project uses Conventional Commits. All commit messages are validated by the .githooks/commit-msg hook.

Format¶

type(scope): description

[optional body]

[optional footer(s)]

First line must be ≤ 72 characters
Body and footer are optional, separated by blank lines

Allowed types¶

Type	When to use
`feat`	A new feature
`fix`	A bug fix
`docs`	Documentation only
`style`	Formatting, whitespace (no logic change)
`refactor`	Code change that neither fixes a bug nor adds a feature
`test`	Adding or updating tests
`chore`	Maintenance tasks (deps, configs, tooling)
`perf`	Performance improvement
`ci`	CI/CD pipeline changes
`build`	Build system or dependency changes
`revert`	Reverting a previous commit

Scope¶

Optional. Use the module name or area of change in parentheses:

feat(school): add campus entity
fix(canteen): resolve null pointer in order lookup
ci(system): add integration test stage

Breaking changes¶

Add ! after the type/scope to flag a breaking change:

feat(school)!: redesign student enrollment API
refactor!: remove deprecated auth middleware

Hotfix tag¶

Append [hotfix] to the commit message to skip tests in CI. This is reserved for emergency production fixes only.

fix(auth): patch session token crash [hotfix]

The [hotfix] tag goes at the end of the subject line
The full line (including tag) must still be ≤ 72 characters
A follow-up commit without [hotfix] must be pushed within 24 hours to restore test coverage
See CICD.md § Hotfix Protocol for the full procedure

Examples¶

Valid:

feat(school): add campus entity
fix: resolve null pointer in student lookup
docs: update AI_CONTEXT with commit conventions
test(sample): add pagination edge case tests
chore: bump Spring Boot to 3.3.1
refactor(canteen)!: redesign order processing

Invalid:

added stuff                          # missing type
feat add campus                      # missing colon
feat:add campus                      # missing space after colon
FEAT(school): add campus             # type must be lowercase
feat(school): Add campus entity.     # no trailing period, lowercase first char preferred