Best Practices
Commit message conventions
Use a consistent commit message structure to improve log readability, release notes quality, and incident-time traceability.
- Individuals or teams who want more predictable Git habits
- Maintainers setting collaboration expectations
- At least one real collaboration loop
- Basic command familiarity without a stable routine yet
- Treating guidance as absolute law without context
- Memorizing process without understanding team boundaries
Commit messages are long-term operational metadata, not just local notes.
A practical structure
<type>(<scope>): <summary>
In body text, include:
- why this changed
- what risk or follow-up remains
Define change scopeChoose type prefixWrite clear description
Readable historyAuto categorizationDocs generation ready
A good message is not for yourself now, but for yourself in six months and your teammates.
Example
fix(auth): reject expired refresh token
Align backend token validation with new TTL rule.
Risk: may increase login retries for stale clients.
Team-level rules
- start summaries with an action verb
- explain motivation, not only file edits
- mark breaking changes explicitly
PR context may be collapsed or lost over time. Commit history remains the durable searchable index.
Good follow-up reads
commit hygieneprepare commits before pull requestsmall batch review