-
Notifications
You must be signed in to change notification settings - Fork 0
docs(standards): org engineering standards + editorial README template #24
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
16ad039
docs(standards): add org engineering standards + restyle README template
WomB0ComB0 e6a030a
Update README.template.md
WomB0ComB0 3209caa
Update docs/standards/04-security.md
WomB0ComB0 f14d7a2
docs(standards): align tier wording + fix security-scan link target
WomB0ComB0 dd97a82
Merge branch 'main' into feat/engineering-standards-and-readme-style
WomB0ComB0 d4e10c4
docs(standards): move #![forbid(unsafe_code)] out of the cargo comman…
WomB0ComB0 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| # Tier 1 — Repo-wide Baseline | ||
|
|
||
| Applies to **every** repository, regardless of language. If a repo can't meet a | ||
| baseline rule, that's a written deviation in its `AGENTS.md`, not a silent skip. | ||
|
|
||
| ## Required toolchain | ||
|
|
||
| Every repo must have, wired into CI via the org `required` check: | ||
|
|
||
| - **Formatter** — runs in CI in check mode; no unformatted code on `main`. | ||
| - **Linter** — runs in CI; warnings are errors in CI (`-D warnings`-style). | ||
| - **Type checker** — where the language has one (TS, Python, C#); enabled in | ||
| strict mode. | ||
| - **Tests** — for any non-trivial logic. New behavior ships with a test. | ||
| - **Security scan** — the org `security-scan.yml` (CodeQL/OSV/Dependency Review/ | ||
| zizmor/actionlint, opt-in Gitleaks/Semgrep/Snyk). | ||
|
|
||
| ## Hard rules | ||
|
|
||
| ```text | ||
| No secrets in code. Use env vars or a secret manager; validate at startup. | ||
| No unchecked external input. Validate at every trust boundary; fail closed. | ||
| No unbounded retries. Every retry loop has a max attempt count + backoff. | ||
| No missing timeouts. Every network / IO call has an explicit timeout. | ||
| No silent catch/except. Handle, wrap, or propagate — never swallow. | ||
| No TODOs in production paths. Unless linked to a tracked issue. | ||
| No hand-edited generated files. Regenerate; edit the source/template. | ||
| No mutation where avoidable. Prefer immutable data; localize necessary mutation. | ||
| ``` | ||
|
|
||
| ## Code shape | ||
|
|
||
| These are defaults; languages may override in [Tier 2](./02-languages.md) where | ||
| idioms differ (e.g. Go pointer receivers). | ||
|
|
||
| - **Functions** focused — aim < 50 lines; extract when responsibilities stack. | ||
| - **Files** cohesive — 200–400 lines typical, 800 max; many small files over few | ||
| large ones. | ||
| - **Nesting** shallow — prefer early returns over > 4 levels of nesting. | ||
| - **Names** descriptive — `camelCase`/`snake_case` per language; booleans read as | ||
| `is`/`has`/`should`/`can`; constants `UPPER_SNAKE_CASE`. | ||
| - **No magic numbers** — name meaningful thresholds, delays, limits. | ||
|
|
||
| ## Errors & logging | ||
|
|
||
| - Handle errors explicitly at every layer; user-facing messages stay friendly, | ||
| server-side logs carry the detail. | ||
| - Structured logs (key/value or JSON), not `print`-debugging left in. | ||
| - Never leak secrets, tokens, or PII into logs or error messages. | ||
|
|
||
| ## Repository hygiene | ||
|
|
||
| Enforced by [`repo-standards.yml`](../../.github/workflows/repo-standards.yml): | ||
|
|
||
| - A detectable `LICENSE` (Apache-2.0 unless a repo declares otherwise). | ||
| - A real `README.md` — start from [`README.template.md`](../../README.template.md); | ||
| no leftover `{{PLACEHOLDER}}` tokens. | ||
| - Org community-health files (`CONTRIBUTING`, `SECURITY`, `CODE_OF_CONDUCT`, | ||
| `SUPPORT`) are inherited org-wide from this repo — don't duplicate unless | ||
| overriding. | ||
| - Conventional Commits + the branch-name pattern (see [`CONTRIBUTING.md`](../../CONTRIBUTING.md)). | ||
|
|
||
| ## Definition of done | ||
|
|
||
| - [ ] Formatter, linter, type-checker, tests, security scan green (`required` ✓) | ||
| - [ ] No secrets, no swallowed errors, no unbounded loops/timeouts | ||
| - [ ] New behavior covered by tests | ||
| - [ ] Public API / behavior change reflected in docs and CHANGELOG | ||
| - [ ] Any standards deviation documented in `AGENTS.md` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| # Tier 2 — Language Enforcement | ||
|
|
||
| Per-language tooling and idioms. A repo's `lang` custom property selects which | ||
| section applies; polyglot repos apply every relevant section. These extend | ||
| [Tier 1](./01-baseline.md) and override it where the language idiom differs. | ||
|
|
||
| --- | ||
|
|
||
| ## TypeScript | ||
|
|
||
| The most important move is **strictness**, not style. | ||
|
|
||
| - `tsconfig.json` extends a strict base: | ||
| ```jsonc | ||
| { | ||
| "compilerOptions": { | ||
| "strict": true, | ||
| "noImplicitOverride": true, | ||
| "noUncheckedIndexedAccess": true, | ||
| "exactOptionalPropertyTypes": true, | ||
| "noFallthroughCasesInSwitch": true | ||
| } | ||
| } | ||
| ``` | ||
| - No `any`. Use `unknown` at trust boundaries and narrow. | ||
| - Validate all external data (API responses, env, user input) with Zod / Valibot | ||
| / TypeBox before it enters typed code. | ||
| - Lint with [typescript-eslint](https://typescript-eslint.io/) recommended + | ||
| type-checked configs. Format with Prettier/Biome. Base style: Google TS guide. | ||
|
|
||
| ## JavaScript (legacy / scripts / Node tooling) | ||
|
|
||
| - ESLint recommended; prefer migrating to TypeScript when a file grows logic. | ||
| - Google JS style guide as the base; prefer ESM. | ||
|
|
||
| ## Python | ||
|
|
||
| - [PEP 8](https://peps.python.org/pep-0008/) + [PEP 257](https://peps.python.org/pep-0257/) baseline; Google Python style for structure. | ||
| - Tooling: **Ruff** (lint + format), **Pyright** or **mypy** (strict), **pytest**, | ||
| **Bandit** (SAST), **pip-audit** (deps). Manage with **uv**. | ||
| - Type-hint public functions; `from __future__ import annotations` where helpful. | ||
|
|
||
| ## C\# | ||
|
|
||
| - [Microsoft .NET coding conventions](https://learn.microsoft.com/dotnet/csharp/fundamentals/coding-style/coding-conventions); Google C# guide only when aligning a polyglot repo to Google style. | ||
| - `dotnet format` + `.editorconfig`; `<Nullable>enable</Nullable>`; treat warnings | ||
| as errors where practical; Roslyn analyzers (`Microsoft.CodeAnalysis.NetAnalyzers`). | ||
| - Prefer `async`/`await` end-to-end; no `.Result`/`.Wait()` deadlock traps. | ||
|
|
||
| ## Rust | ||
|
|
||
| Discipline is mostly compiler-enforced. | ||
|
|
||
| ```text | ||
| cargo fmt --check | ||
| cargo clippy -- -D warnings | ||
| cargo test | ||
| cargo audit | ||
| cargo deny check | ||
| ``` | ||
|
WomB0ComB0 marked this conversation as resolved.
|
||
|
|
||
| - Add `#![forbid(unsafe_code)]` at the crate root where the crate allows it | ||
| (it's a source attribute, not a CLI flag). | ||
| - Follow the [Rust API Guidelines](https://github.com/rust-lang/api-guidelines) | ||
| for public surfaces. | ||
| - Treat every `unsafe` block as a mini C island: document the invariants, | ||
| isolate it, review it, test it, fuzz it. See [Tier 3](./03-safety-overlay.md). | ||
|
|
||
| ## C / C++ | ||
|
|
||
| Tooling baseline; the analyzability rules live in [Tier 3](./03-safety-overlay.md). | ||
|
|
||
| - `clang-format` + `clang-tidy`; build clean at `-Wall -Wextra -Werror`. | ||
| - Sanitizers (ASan/UBSan/TSan) in test builds; static analysis in CI. | ||
| - C++: modern, RAII, smart pointers, STL; avoid raw `new`/`delete`, RTTI-heavy | ||
| designs, and clever template metaprogramming without a systems reason. | ||
|
|
||
| ## Shell | ||
|
|
||
| - [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html); | ||
| **ShellCheck** clean. `set -euo pipefail` (bash) / `set -eu` (POSIX sh). | ||
| - Quote every expansion. Prefer `printf` over `echo` for data. Bound every loop. | ||
|
|
||
| ## SQL | ||
|
|
||
| - **SQLFluff** for lint/format; consistent naming (snake_case tables/columns). | ||
| - Parameterized queries only — never string-concatenate user input. | ||
| - Migrations are forward-only and reviewed; every query that can grow is bounded | ||
| (`LIMIT`, pagination). | ||
|
|
||
| ## Markdown / JSON / YAML | ||
|
|
||
| - Prettier (md/json/yaml) + **yamllint**; Google Markdown guide for docs. | ||
| - Workflow YAML: **actionlint** + **zizmor** (already in `security-scan.yml`). | ||
|
|
||
| --- | ||
|
|
||
| ## Release & versioning | ||
|
|
||
| Conventional Commits drive versioning. Per-ecosystem tooling (release-it, PSR, | ||
| cargo-release/release-plz, MinVer) is documented in the | ||
| [README template's automation appendix](../../README.template.md). | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.