mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 15:03:14 +00:00
84 lines
2.2 KiB
Markdown
84 lines
2.2 KiB
Markdown
|
# Commit Messages
|
||
|
|
|
||
|
|
> Adapted from [commit-messages-guide](https://github.com/RomuloOliveira/commit-messages-guide) by Romulo Oliveira, licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/).
|
||
|
|
|
||
|
|
## Rules
|
||
|
|
|
||
|
|
### Use imperative mood
|
||
|
|
|
||
|
|
Write what the commit *does*, not what you *did*.
|
||
|
|
|
||
|
|
| Good | Bad |
|
||
|
|
|---|---|
|
||
|
|
| Add retry logic to payment processor | Added retry logic to payment processor |
|
||
|
|
| Fix null check in auth handler | Fixed null check in auth handler |
|
||
|
|
| Remove deprecated endpoint | Removing deprecated endpoint |
|
||
|
|
|
||
|
|
### Capitalize the first letter
|
||
|
|
|
||
|
|
| Good | Bad |
|
||
|
|
|---|---|
|
||
|
|
| Fix null check in auth handler | fix null check in auth handler |
|
||
|
|
|
||
|
|
### Keep the subject line under 50 characters
|
||
|
|
|
||
|
|
The subject line is for scanning. Details go in the body.
|
||
|
|
|
||
|
|
### Wrap the body at 72 characters
|
||
|
|
|
||
|
|
If you need to explain more, add a blank line after the subject and write a body wrapped at 72 characters per line.
|
||
|
|
|
||
|
|
### Explain "why," not "what"
|
||
|
|
|
||
|
|
The diff shows what changed. The commit message should explain why.
|
||
|
|
|
||
|
|
| Good | Bad |
|
||
|
|
|---|---|
|
||
|
|
| Increase timeout to handle slow upstream responses | Change timeout from 30 to 60 |
|
||
|
|
| Switch to arm64 to reduce Lambda cold start cost | Update architecture setting |
|
||
|
|
|
||
|
|
### No generic messages
|
||
|
|
|
||
|
|
These are not acceptable:
|
||
|
|
|
||
|
|
- `Fix stuff`
|
||
|
|
- `Update code`
|
||
|
|
- `WIP`
|
||
|
|
- `Misc changes`
|
||
|
|
- `Address review comments`
|
||
|
|
|
||
|
|
Every commit should describe a specific change.
|
||
|
|
|
||
|
|
### No self-referential language
|
||
|
|
|
||
|
|
| Good | Bad |
|
||
|
|
|---|---|
|
||
|
|
| Fix race condition in queue processor | This commit fixes a race condition |
|
||
|
|
| Add input validation for email field | This PR adds validation |
|
||
|
|
| Refactor auth middleware for clarity | I refactored the auth middleware |
|
||
|
|
|
||
|
|
## Template
|
||
|
|
|
||
|
|
```
|
||
|
|
Subject line (50 chars max, imperative, capitalized)
|
||
|
|
|
||
|
|
Optional body wrapped at 72 characters. Explain the problem
|
||
|
|
this commit solves and why this approach was chosen. Mention
|
||
|
|
side effects or non-obvious consequences.
|
||
|
|
|
||
|
|
Refs: #123
|
||
|
|
```
|
||
|
|
|
||
|
|
## Example
|
||
|
|
|
||
|
|
```
|
||
|
|
Add retry logic for transient upstream failures
|
||
|
|
|
||
|
|
The payment processor occasionally returns 503 during
|
||
|
|
deployments. Without retries, these surface as user-facing
|
||
|
|
errors. This adds exponential backoff with 3 attempts,
|
||
|
|
which matches the upstream's documented recovery window.
|
||
|
|
|
||
|
|
Refs: #45
|
||
|
|
```
|