mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 19:43:14 +00:00

Adam Moussa 0333e7f8f5 Add engineering handbook

Conventions covering naming, git workflow, commit messages, pull
requests, code review, GitHub standards, AWS infrastructure, SAM
project layout, and secrets management. Commit messages section
adapted from RomuloOliveira/commit-messages-guide (CC-BY-4.0).

2026-05-02 16:42:44 -04:00

1.5 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 imperative mood, same as commit messages
Describe the change, not the ticket

Good	Bad
Add retry logic for transient upstream failures	JIRA-123
Fix null check in auth handler	Bug fix
Update Lambda runtime to Python 3.12	Updates

Description

Use a structured format:

## Summary
Brief explanation of what this PR does and why.

## Changes
- Bullet list of specific changes

## Test Plan
- How you verified this works
- What to check during review

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.5 KiB Raw Blame History