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

docs: adopt conventional commit format as the org standard

Make Conventional Commits (type(scope): description) the canonical
commit and PR-title format across Sea Haven, replacing the previous
imperative/capitalized/no-prefix rule.

- commit-messages.md: full rewrite to the type(scope): description
  format with the type table, lowercase/imperative description rules,
  breaking-change (! + BREAKING CHANGE footer) guidance tied to SemVer,
  and updated template and examples.
- git-workflow.md: extend the branch-prefix table with chore/, docs/,
  refactor/, and release/ (alongside the existing feature/bug/hotfix),
  mirroring the commit types.
- pull-requests.md: reconcile the title rule to the Conventional Commit
  format.
- README.md: update the commit-messages one-line summary.

Refs: INFRA-57

2026-07-17 19:30:02 -04:00

1.8 KiB

Raw Blame History

Pull Requests

Scope

Each PR should represent a single logical change. If you find yourself writing "and" in the title, consider splitting it into separate PRs.

Good scope	Too broad
Add receipt parser Lambda	Add receipt parser and refactor auth middleware
Fix timeout in payment processor	Fix timeout and update dependencies
Update Lambda runtime to Python 3.12	Update runtime and add new endpoint

Title

Keep it under 70 characters
Use the Conventional Commit format, same as commit messages (type(scope): description)
Describe the change, not the ticket

Good	Bad
`feat: add retry logic for transient upstream failures`	`JIRA-123`
`fix: correct null check in auth handler`	`Bug fix`
`build: update Lambda runtime to Python 3.12`	`Updates`

Description

Use a structured format:

## Summary
What changed and why — 1-3 sentences. Explain the motivation, not just the diff.

## Validation
How you verified it works — steps taken, commands run, screenshots if UI.

## Tests
What tests were added, updated, or run. If no automated tests, explain manual testing.

## Notes
Anything reviewers should know — migration steps, deploy order, follow-ups, breaking changes. Omit this section if empty.

The summary should explain why the change is needed, not just restate the diff. Reviewers can read the code; they need context.

When to Open a PR

Before deploying to production (see deploy-then-merge workflow)
When the work is ready for review, not as a draft for parking incomplete work
After verifying locally that the change works as expected

Merging

Squash merge for feature branches with messy interim commits
Regular merge for branches with clean, meaningful commit history
Delete the branch after merge

1.8 KiB Raw Blame History