mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 19:43:14 +00:00
e749e6f651
Work is tracked in Jira while code lives in GitHub; the org-level GitHub for Jira app is already installed but nothing told contributors how to trigger the link. Document putting the Jira key in the branch name, PR title, or Refs trailer so branches, commits, and PRs thread into the issue's development panel. Use a generic PROJ-123 placeholder rather than naming specific projects, which change over time.
92 lines
2.8 KiB
Markdown
92 lines
2.8 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: PROJ-123, #123
|
|
```
|
|
|
|
## Referencing issues
|
|
|
|
Use the `Refs:` trailer to point at the work this commit relates to:
|
|
|
|
- **Jira key** (`PROJ-123`) when the work tracks a Jira issue. The GitHub for Jira app reads the key and threads the commit into the issue's development panel. See [git-workflow.md](git-workflow.md#linking-to-jira).
|
|
- **GitHub issue** (`#123`) when the work tracks a GitHub issue in the same repo.
|
|
|
|
List both when both apply: `Refs: PROJ-123, #123`. The key only needs to appear once in the branch, PR title, or any commit for the link to form, but including it in the trailer keeps the reference attached to the individual change.
|
|
|
|
## 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: PROJ-123
|
|
```
|