mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 04:33:13 +00:00
Engineering conventions and best practices for Sea Haven Industries
Adam Moussa
855b473479
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 |
||
|---|---|---|
| .github/workflows | ||
| constructs | ||
| hooks | ||
| scripts | ||
| .markdownlint-cli2.jsonc | ||
| aws-infrastructure.md | ||
| bedrock.md | ||
| cdk-project-layout.md | ||
| cicd.md | ||
| code-review-rubric.md | ||
| code-review.md | ||
| commit-messages.md | ||
| CONTRIBUTING.md | ||
| dev-environment.md | ||
| git-workflow.md | ||
| github-standards.md | ||
| lambda-template.md | ||
| LICENSE | ||
| lychee.toml | ||
| naming-conventions.md | ||
| pull-requests.md | ||
| README.md | ||
| sam-project-layout.md | ||
| secrets-and-config.md | ||
Engineering Handbook
Engineering conventions and best practices for Sea Haven Industries.
Contents
- Naming Conventions -- kebab-case everywhere, no exceptions
- Development Environment -- workstation directory layout, pyenv, Node, launchd/TCC
- Git Workflow -- feature branches, incremental commits, deploy-then-merge
- Commit Messages -- Conventional Commits, type(scope) format, explain "why"
- Pull Requests -- scope, title, description format, merge strategy
- Code Review -- what to look for, giving feedback, turnaround expectations
- Code Review Rubric -- BLOCK/FIX/NIT/QUESTION finding categories and output format
- GitHub Standards -- branch defaults, repo hygiene, Dependabot
- AWS Infrastructure -- SAM vs CDK, Lambda defaults, CloudFormation
- SAM Project Layout -- standard directory structure for serverless projects
- CDK Project Layout -- standard directory structure for CDK projects
- Lambda Starter Template -- minimal SAM scaffold for a new Python Lambda
- Secrets and Configuration -- Secrets Manager vs SSM Parameter Store
- CI/CD Pipelines -- every deployable repo gets a pipeline, no manual deploys
- Bedrock -- cross-region inference profiles, alias pinning, KB Docker requirement
- Git Hooks -- recommended pre-push and pre-commit hooks
- Scripts -- repo provisioning, automation tooling
- CDK Constructs -- shared VPN EC2 instance construct and other reusable patterns
Contributing
See CONTRIBUTING.md.
License
This work is licensed under CC-BY-4.0. The commit messages section adapts content from commit-messages-guide by Romulo Oliveira, also licensed under CC-BY-4.0.