adam/engineering-handbook
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 06:53:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
engineering-handbook/README.md

40 lines
2.6 KiB
Markdown
Raw Normal View History

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
# Engineering Handbook
Repo hygiene: PR labeler + README badges (INFRA-56/57) (#13)
2026-06-11 14:14:17 -04:00
![Docs](https://img.shields.io/badge/Docs-Handbook-0c4f6f?logo=readthedocs&logoColor=white)
![Shell](https://img.shields.io/badge/Shell-121011?logo=gnu-bash&logoColor=white)
![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey?logo=creativecommons&logoColor=white)
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
Engineering conventions and best practices for Sea Haven Industries.
## Contents
- [Naming Conventions](naming-conventions.md) -- kebab-case everywhere, no exceptions
Add Bedrock, dev-env, and Lambda template pages (#7) Adds three handbook pages covering conventions that were previously scattered across feedback memories or rederived from scratch each time: - bedrock.md captures the cross-region inference profile requirement for Claude 4.x Bedrock Agents and the alias-version pinning gotcha, plus the IAM resource pattern and the KB Docker requirement. - dev-environment.md documents the workstation directory layout, pyenv/Node conventions, the macOS launchd/TCC sandbox gotcha, and cleanup cadence. - lambda-template.md provides a minimal SAM scaffold that follows the Lambda defaults already in aws-infrastructure.md (Python 3.12, arm64, explicit 60-day log retention, scoped Secrets Manager access, module-level secret cache). Also extends two existing pages: - sam-project-layout.md gains a Lambda Layers section with the BuildMethod nesting pattern that caused a ~22-hour production outage when violated. - naming-conventions.md adds a Legacy Stacks note acknowledging that pre-convention PascalCase stacks (SeaHavenDoorUnlockStack, WorkorderIngestStack) stay as-is rather than risk stack replacement.
2026-05-14 19:50:37 -04:00
- [Development Environment](dev-environment.md) -- workstation directory layout, pyenv, Node, launchd/TCC
docs(issue-tracking): add Jira ticket format standard
2026-07-31 14:16:39 -04:00
- [Issue Tracking](issue-tracking.md) -- Jira projects, ticket description template, ticket hygiene
docs(cd): separate terraform infra from github app deploys (#46) Make HCP Terraform plus GitHub Actions content CD the default for new workloads, and keep SAM/CDK documented as the remaining path.
2026-09-15 22:05:33 +00:00
- [Git Workflow](git-workflow.md) -- feature branches, incremental commits, merge to main then release for prod
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
- [Commit Messages](commit-messages.md) -- Conventional Commits, type(scope) format, explain "why"
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
- [Pull Requests](pull-requests.md) -- scope, title, description format, merge strategy
- [Code Review](code-review.md) -- what to look for, giving feedback, turnaround expectations
Add CDK layout and code review rubric to handbook index Both pages existed in working drafts but were not linked from the README table of contents, so they were undiscoverable. Add them to the index alongside the related SAM layout and code review pages.
2026-06-02 19:36:09 -04:00
- [Code Review Rubric](code-review-rubric.md) -- BLOCK/FIX/NIT/QUESTION finding categories and output format
docs(cd): separate terraform infra from github app deploys (#46) Make HCP Terraform plus GitHub Actions content CD the default for new workloads, and keep SAM/CDK documented as the remaining path.
2026-09-15 22:05:33 +00:00
- [GitHub Standards](github-standards.md) -- branch defaults, repo hygiene, Environments
- [AWS Infrastructure](aws-infrastructure.md) -- HCP Terraform default, remaining SAM/CDK, Lambda defaults
- [HCP Terraform](hcp-terraform.md) -- workspaces, seam, SSM deploy contract, exec roles
- [Terraform Project Layout](terraform-project-layout.md) -- standard directory structure for HCP app repos
- [SAM Project Layout](sam-project-layout.md) -- remaining path for existing SAM stacks
- [CDK Project Layout](cdk-project-layout.md) -- remaining path for CDK and Bedrock
- [Lambda Starter Template](lambda-template.md) -- remaining SAM scaffold for a Python Lambda
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
- [Secrets and Configuration](secrets-and-config.md) -- Secrets Manager vs SSM Parameter Store
docs(cd): separate terraform infra from github app deploys (#46) Make HCP Terraform plus GitHub Actions content CD the default for new workloads, and keep SAM/CDK documented as the remaining path.
2026-09-15 22:05:33 +00:00
- [CI/CD Pipelines](cicd.md) -- HCP lane default, remaining SAM/CDK reusables
Add Bedrock, dev-env, and Lambda template pages (#7) Adds three handbook pages covering conventions that were previously scattered across feedback memories or rederived from scratch each time: - bedrock.md captures the cross-region inference profile requirement for Claude 4.x Bedrock Agents and the alias-version pinning gotcha, plus the IAM resource pattern and the KB Docker requirement. - dev-environment.md documents the workstation directory layout, pyenv/Node conventions, the macOS launchd/TCC sandbox gotcha, and cleanup cadence. - lambda-template.md provides a minimal SAM scaffold that follows the Lambda defaults already in aws-infrastructure.md (Python 3.12, arm64, explicit 60-day log retention, scoped Secrets Manager access, module-level secret cache). Also extends two existing pages: - sam-project-layout.md gains a Lambda Layers section with the BuildMethod nesting pattern that caused a ~22-hour production outage when violated. - naming-conventions.md adds a Legacy Stacks note acknowledging that pre-convention PascalCase stacks (SeaHavenDoorUnlockStack, WorkorderIngestStack) stay as-is rather than risk stack replacement.
2026-05-14 19:50:37 -04:00
- [Bedrock](bedrock.md) -- cross-region inference profiles, alias pinning, KB Docker requirement
Merge pull request #28: docs: align engineering conventions for Cursor migration (PLAT-62) docs: align engineering conventions for Cursor migration (PLAT-62)
2026-08-03 18:01:08 -04:00
- [Git Hooks](hooks/) -- shim for the global security pre-push hook
Add CDK version policy, update Node 24 and GitHub Actions CI/CD (#6) * Update CDK version policy, Node 24 runtime, and GitHub Actions CI/CD - Pin blessed aws-cdk-lib version (2.253.1) with upgrade procedure - Update Lambda runtime default from Node 22 to Node 24 - Rewrite CI/CD page to reflect GitHub Actions reusable workflows (was still referencing CodePipeline/CodeBuild) * Add pre-push hook for npm ci validation Catches lock file drift locally before it breaks CI. Includes install instructions in git-workflow.md. * Add repo provisioning script Automates the new-repo checklist: GitHub repo creation, OIDC deploy role, repo secret, security features, CI/CD workflow stubs, and pre-push hook installation. Supports both SAM and CDK stack types. * Add shared VpnEc2Instance CDK construct Reference construct for the VPN-accessible EC2 pattern used by file-share and forgejo. Includes VPC/subnet lookup, SG, IAM role, encrypted EBS, and DLM snapshots. Copy into lib/constructs/. * Add post-deploy health check template Template script for project-specific health checks. Copy to scripts/health-check.sh — CD workflows run it automatically.
2026-05-14 18:39:13 -04:00
- [Scripts](scripts/) -- repo provisioning, automation tooling
- [CDK Constructs](constructs/) -- shared VPN EC2 instance construct and other reusable patterns
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
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
This work is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). The commit messages section adapts content from [commit-messages-guide](https://github.com/RomuloOliveira/commit-messages-guide) by Romulo Oliveira, also licensed under CC-BY-4.0.
Reference in a new issue Copy permalink