Commit Message Standards
Clear commit messages create a readable project history and help during debugging.
Branch Commits (Incremental Work)
Goal: capture the intent of the change so teammates and future developers can understand the progression.
- Keep it short and clear: a single sentence is fine
- Focus on what changed and why, not perfect formatting
- Use whatever structure the repository already uses (Conventional Commits optional, not required)
Examples (branch commits):
Add filter options to results table
Fix null check in risk score calculation
Update README with setup steps
Merge to Main (Squash Commit Message)
Goal: be more specific and user-facing than branch commits. This is the permanent record for the release history.
- Summarize the primary outcome of the PR
- Include impact or scope (feature area, user behavior, or system behavior)
- If the PR is large, add a short body with 2-4 bullets
Examples (merge commits):
Add export options to report builder (PDF, CSV)
- Adds export menu to analysis results
- Generates CSV with normalized headers
- Updates tests for export pipeline
Fix duplicate submission bug in hazard form
Commit Frequency
- Commit early and often - Small, logical commits are better than large ones
- Each commit should be a complete thought - Should be able to revert without breaking functionality
- Push daily - Even unfinished work should be pushed to remote for backup