mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 22:03:13 +00:00

Adam Moussa e749e6f651 Add Jira issue-linking convention

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.

2026-06-02 19:36:03 -04:00

2.8 KiB

Raw Blame History

Commit Messages

Adapted from commit-messages-guide by Romulo Oliveira, licensed under CC-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.
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

2.8 KiB Raw Blame History