mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 05:43:15 +00:00
Engineering conventions and best practices for Sea Haven Industries
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. |
||
|---|---|---|
| constructs | ||
| hooks | ||
| scripts | ||
| aws-infrastructure.md | ||
| bedrock.md | ||
| cicd.md | ||
| code-review.md | ||
| commit-messages.md | ||
| CONTRIBUTING.md | ||
| dev-environment.md | ||
| git-workflow.md | ||
| github-standards.md | ||
| lambda-template.md | ||
| LICENSE | ||
| 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 -- imperative mood, 50/72 rule, explain "why"
- Pull Requests -- scope, title, description format, merge strategy
- Code Review -- what to look for, giving feedback, turnaround expectations
- GitHub Standards -- branch defaults, repo hygiene, Dependabot
- AWS Infrastructure -- SAM vs CDK, Lambda defaults, CloudFormation
- SAM Project Layout -- standard directory structure for serverless 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.