mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 09:13:14 +00:00
Adam Moussa
a4742fc97b
Capture the org conventions rolled out in the INFRA-47 hygiene pass: - github-standards.md: static-only README badges (dynamic shields break on private repos; CI badge is member-only) and a lowercase-hyphenated repo topic vocabulary, both part of new-repo provisioning. - cicd.md: the central inline-config reusable PR labeler — pull_request trigger, the three required caller permissions, no per-repo labeler.yml.
133 lines
4.7 KiB
Markdown
133 lines
4.7 KiB
Markdown
# GitHub Standards
|
|
|
|
## Repository Defaults
|
|
|
|
- Default branch: `main`
|
|
- Every repo gets a one-line description
|
|
- Every repo gets standard topics and a README badge block (see below)
|
|
- Default to `private` visibility for org repos
|
|
- Dependabot alerts and security updates enabled on all active repos
|
|
- Org-level defaults auto-enable alerts and security updates on new repos
|
|
- Every repo with dependencies gets a `.github/dependabot.yml` for weekly version updates
|
|
|
|
## Dependabot Configuration
|
|
|
|
Every active repo with package dependencies must have a `.github/dependabot.yml` that covers all relevant ecosystems.
|
|
|
|
### Pinning Principle
|
|
|
|
Exact pins are for reproducibility, not for freezing time. The pinned version is kept current by Dependabot version updates gated by CI and dependency review — never by a version number written in documentation.
|
|
|
|
- Never add a blanket `ignore` entry for a dependency. If a specific release is broken, ignore that release only (`versions: ["x.y.z"]`), with a comment, and remove the entry once a fixed release ships.
|
|
- Never dismiss a vulnerability alert as "waiting for upstream" without a linked follow-up that advances the pin when the fix ships.
|
|
- If a bump PR fails CI, the gate worked — leave the bad release unmerged and take the next one.
|
|
|
|
### Ecosystem Selection
|
|
|
|
Choose ecosystems based on what dependency files exist in the repo:
|
|
|
|
| File | Ecosystem |
|
|
|------|-----------|
|
|
| `package.json` | `npm` |
|
|
| `requirements.txt` | `pip` |
|
|
| `.csproj` | `nuget` |
|
|
| `.github/workflows/*.yml` | `github-actions` |
|
|
|
|
### Standard Templates
|
|
|
|
**Single ecosystem (npm or pip):**
|
|
|
|
```yaml
|
|
version: 2
|
|
updates:
|
|
- package-ecosystem: "npm" # or "pip", "nuget", "github-actions"
|
|
directory: "/"
|
|
schedule:
|
|
interval: "weekly"
|
|
```
|
|
|
|
**SAM project with per-function `requirements.txt`:**
|
|
|
|
Add a separate entry for each directory containing a `requirements.txt`:
|
|
|
|
```yaml
|
|
version: 2
|
|
updates:
|
|
- package-ecosystem: "pip"
|
|
directory: "/src/processor"
|
|
schedule:
|
|
interval: "weekly"
|
|
- package-ecosystem: "pip"
|
|
directory: "/src/receiver"
|
|
schedule:
|
|
interval: "weekly"
|
|
```
|
|
|
|
**Mixed ecosystems (e.g., CDK in JS with Python Lambdas, or repos with GitHub Actions):**
|
|
|
|
Add one entry per ecosystem/directory:
|
|
|
|
```yaml
|
|
version: 2
|
|
updates:
|
|
- package-ecosystem: "npm"
|
|
directory: "/"
|
|
schedule:
|
|
interval: "weekly"
|
|
- package-ecosystem: "pip"
|
|
directory: "/src"
|
|
schedule:
|
|
interval: "weekly"
|
|
- package-ecosystem: "github-actions"
|
|
directory: "/"
|
|
schedule:
|
|
interval: "weekly"
|
|
```
|
|
|
|
### Merging Dependabot PRs
|
|
|
|
- **Patch and minor bumps:** Safe to merge without review in most cases
|
|
- **Major version bumps:** Review changelog for breaking changes before merging
|
|
- When merging multiple Dependabot PRs, merge one at a time — subsequent PRs will auto-rebase
|
|
|
|
## Branch Protection
|
|
|
|
- Require a PR for merges to `main` (no direct push)
|
|
- No force push to `main`
|
|
- No branch deletion for `main`
|
|
|
|
## README Badges
|
|
|
|
Every repo's README carries a small badge block immediately under the H1. Use **static** badges only — dynamic badges (for example shields.io `last-commit` or `open-issues`) query the public GitHub API and render broken on private repos.
|
|
|
|
- **CI status:** the GitHub-native workflow badge (`.../actions/workflows/<ci-file>/badge.svg`), and only when a CI workflow exists. On private repos it renders only for logged-in org members — that is accepted.
|
|
- **Stack:** two to four static shields.io badges for the language and IaC/runtime (Python / TypeScript / .NET, AWS SAM / CDK), plus a Slack badge when the repo integrates Slack.
|
|
- Keep badges static so they never go stale; version-pinned badges drift.
|
|
|
|
## Repository Topics
|
|
|
|
Every repo gets a set of lowercase, hyphenated topics so the org is filterable by stack and purpose. Draw from a consistent vocabulary:
|
|
|
|
- **Cloud / IaC:** `aws`, `sam`, `cdk`, `lambda`, `ec2`, `s3`, `cloudfront`
|
|
- **Language:** `python`, `typescript`, `javascript`, `dotnet`, `react`, `nodejs`
|
|
- **Integration / domain:** `slack`, `bedrock`, `ai`, `security`, `internal-tool`, `documentation`
|
|
|
|
Set them with `gh repo edit <repo> --add-topic a,b,c`. Adding topics is part of new-repo provisioning, not a follow-up.
|
|
|
|
## Repo Hygiene
|
|
|
|
- Delete feature branches after merge
|
|
- Archive repos that are no longer actively developed (close issues first)
|
|
- Don't delete repos unless truly disposable
|
|
- Scrub all company-specific info from git history before making any repo public
|
|
|
|
## Public Repos
|
|
|
|
Before making a repo public, verify the entire git history contains no:
|
|
|
|
- Phone numbers or customer data
|
|
- API subdomains or internal URLs
|
|
- Webhook endpoints
|
|
- Employee names or internal identifiers
|
|
|
|
If sensitive data was committed at any point, start fresh with a clean `git init` rather than rewriting history.
|