Purpose
To enforce consistent commit messages across all repositories, ensuring history is readable, traceable, and automatable for changelogs, CI/CD, and audits.
Scope
- Applies to all developers committing to organization repos.
- Covers commit message format, prefixes, ticket linking, and validation.
- Applies to features, fixes, chores, spikes, hotfixes, and merges.
Objectives
- Ensure commit messages clearly explain what changed and why.
- Enable automated changelogs and semantic versioning.
- Improve collaboration by making history easy to follow.
Step-by-Step Standards
1. Commit Message Format
<type>(<scope>): <short summary> #<ticket-id> <body - optional> <footer - optional>
Example:
feat(auth): add JWT expiry validation #API-124
2. Allowed Types
| Type | When to Use | Example |
| feat | New feature | feat(export): add CSV export |
| fix | Bug fix | fix(auth): resolve null token issue |
| chore | Maintenance/non-functional | chore(deps): upgrade Node v18 |
| docs | Documentation changes | docs(readme): add setup steps |
| style | Formatting only (no code logic change) | style(lint): apply Prettier rules |
| refactor | Code restructure (no new feature/fix) | refactor(payment): simplify retry logic |
| test | Adding/updating tests | test(api): add booking flow tests |
| ci | CI/CD config changes | ci(build): update CircleCI config |
| perf | Performance improvements | perf(query): optimize booking fetch |
| hotfix | Urgent production patch | hotfix(api): patch login crash |
3. Scope Rules
- Scope = module/service/domain name (e.g.,
auth,booking,ui). - For cross-cutting changes: use
coreorglobal.
4. Summary Rules
- Max 72 chars.
- Written in present tense, imperative mood:
fix(auth): validate tokens on refreshfixed/fixes/added
- Should explain what changed, not how.
5. Body (Optional)
- Use when commit is non-trivial.
- Describe why the change was needed, design decisions, or side effects.
- Wrap lines at 100 chars.
6. Footer (Optional)
- Include ticket references, migration notes, or breaking change warnings.
Example:
BREAKING CHANGE: Auth tokens now expire after 15 min Migration: Update all clients to refresh tokens via /refresh endpoint
7. Multiple Commits vs Single Commit
- Prefer multiple small commits during dev.
- Squash into a clean history at merge (per repo policy).
Roles & Responsibilities
| Role | Responsibility |
| Developer | Write commit messages per standard |
| Tech Lead | Review compliance in PRs |
| CI/CD | Validate commit messages automatically (Husky/CommitLint) |
| PM/QA | Trace commits back to tickets |
Governance
- Automated Linting: Use
commitlint+ Husky hooks to enforce format. - Branch Protection: PR cannot merge if commit messages fail validation.
- Audit: Weekly check of commit logs for consistency.
- Exceptions: Hotfixes may bypass body/footer but must follow
<type>(<scope>): summary.