Engineering rules
What a change MUST satisfy to be mergeable. This page is how the rules work. The rules themselves are in the seven pages at the bottom. The reasoning is first principles.
Reading a rule
Requirement levels are RFC 2119 ⧉: MUST, MUST NOT, SHOULD, SHOULD
NOT, MAY. Every rule ends with an Enforcement: line (DOC-10). It says one of
three things.
- A named check, such as
//infra/docker:check-image-pins(pre-commit). A machine rejects the violation. - Review only. A reviewer catches it, or nobody does. Still binding.
- None. Nothing stands behind the rule yet.
See also the enforcement gaps.
Citing a rule
Every rule has an identifier, like BUILD-3 or SERVICE-1, plus an explicit anchor that survives rewording.
Cite it in review comments.
Identifiers are permanent. A new rule takes the next free number in its prefix, wherever it lands on the page. So reading order does not match numeric order. A deleted number is retired, never reused. A comment citing it from a year-old pull request MUST NOT resolve to something else.
A rule MAY move to another prefix. It takes the next free number in the new prefix. You MUST leave a redirect behind, under the old identifier's original anchor. The redirect MUST name the new identifier. It MUST NOT restate the rule. The old number stays retired, so an old citation still reaches the rule and nothing else.
Breaking a rule
- DO say in the pull request which rule you are breaking and why.
- The DRI for that area MUST approve it in the thread before merging. Another reviewer cannot grant it.
- Silence is not approval. An unapproved violation is a defect.
- If you need the same exception over and over, then the rule is wrong. Change it.
Changing a rule
- A rule changes by pull request, like code.
- A stricter rule needs the DRI of every area it binds.
- A looser rule needs the reason on the page, so the next reader sees what was traded away.
- DO replace a rule that no longer holds. DO NOT delete it silently.
Precedence
- These rules.
- The style guides.
- Surrounding code.
A style guide that contradicts a rule is wrong. Fix it in the same pull request.
The rules
| Page | Covers |
|---|---|
| Build rules | BUILD-*: one build path, pinning, images |
| Service rules | SERVICE-*: what every deployed service MUST do |
| Delivery and environment rules | ENV-*, SECURITY-*, INFRA-*: promotion, credentials, infrastructure changes |
| Language rules | GO-*, PYTHON-*, SHELL-* |
| Repository change rules | CHANGE-*, MERGE-*: parallel change, layout, merging |
| Database rules | DB-*: schema migrations |
| Documentation rules | DOC-*: how the wiki is written, and what a documentation change MUST satisfy |