Code Review
Reviewable Changes
Summary
A change remains scoped to the smallest reviewable unit and provides enough context to assess without consulting its author, using the organisation's shared description template.
Standards
- A change SHOULD be scoped to the smallest coherent unit of work that can be reviewed and merged independently.
std-code-reviewable-changes-01 - A change description SHOULD give a reviewer enough context to understand its purpose, effect, and validation without needing to consult the author directly.
std-code-reviewable-changes-02 - An unusually large or broad change SHOULD be split into smaller, independently reviewable changes where practical.
std-code-reviewable-changes-03 - A repository SHOULD use the organisation's shared change-description template.
std-code-reviewable-changes-04
Implements These Principles
Independent Review
Summary
A person other than the author approves each change based on evidence from automated review, manual inspection, or both.
Standards
- A change MUST be approved by at least one person other than its author, familiar with the affected code, system, or domain, before it is merged into a shared or protected branch.
std-code-independent-review-01 - Approval MUST NOT be granted as part of a reciprocal arrangement in which reviewers approve each other's changes without applying meaningful scrutiny.
std-code-independent-review-02 - Where a path's ownership is declared in a
CODEOWNERSfile, approval from the designated owner MUST be enforced before a change to that path can merge.std-code-independent-review-03 - The independent review and human approval requirements MUST apply regardless of a change's size, the seniority of its author, or the review methods used.
std-code-independent-review-04 - Review checks MAY be performed by approved AI agents, CI jobs, manual inspection, or a combination.
std-code-independent-review-05
Related Standards
Implements These Principles
Risk-Based Review
Summary
A higher-risk change receives broader scrutiny and a reviewer with expertise matching that risk.
Standards
- A change MUST be classified as higher-risk if it is security-relevant, makes a breaking schema change, spans multiple services or components, or is hard to roll back.
std-code-risk-based-review-01 - Review scrutiny for a higher-risk change MUST be broader than for a routine change, covering its impact and reversibility.
std-code-risk-based-review-02 - A higher-risk change MUST be reviewed by someone with expertise matching the risk factor involved.
std-code-risk-based-review-03 - A repository MAY document and apply review requirements stricter than the organisation's minimum review requirements.
std-code-risk-based-review-04
Implements These Principles
Review Scope
Summary
The same review process applies to every kind of code a repository holds.
Standards
- The review and approval process MUST apply equally to application code, infrastructure code, configuration, pipeline definitions, and documentation held in the same repository.
std-code-review-scope-01
Implements These Principles
Code Quality & Security
Summary
A reviewer checks a change's correctness, simplicity, maintainability, and security, incorporating automated tooling output and applying judgement where tooling cannot.
Standards
- A reviewer MUST confirm a change is functionally correct and meets its stated requirement before approving it.
std-code-code-quality-security-01 - A reviewer MUST assess whether a change introduces unnecessary complexity or departs from adopted coding and style conventions.
std-code-code-quality-security-02 - Where multiple implementations meet a change's stated requirement equally well, the implementation simplest to understand and maintain SHOULD be selected.
std-code-code-quality-security-03 - Where a more concise implementation would be less readable, the more readable implementation SHOULD be selected.
std-code-code-quality-security-04 - Refactoring SHOULD be performed as part of routine engineering work where code's structure impairs its maintainability.
std-code-code-quality-security-05 - A security-relevant change, such as one that introduces new attack surface or handles sensitive data, MUST be reviewed for security weaknesses relevant to the change.
std-code-code-quality-security-06 - Review SHOULD incorporate relevant output from static analysis or AI-assisted review tooling.
std-code-code-quality-security-07 - A reviewer's own scrutiny SHOULD focus on aspects that static analysis and AI-assisted review tooling cannot reliably assess.
std-code-code-quality-security-08
Related Standards
Implements These Principles
Operational Readiness
Summary
A reviewer considers a change's rollback, observability, performance, consumer, documentation, and release-control implications.
Standards
- A reviewer SHOULD consider whether a change can be rolled back if it does not behave as expected.
std-code-operational-readiness-01 - A reviewer SHOULD consider whether a change meets its observability requirements, such as logging, metrics, or alerting adequate to detect a problem with it after release.
std-code-operational-readiness-02 - A reviewer SHOULD consider whether a change could degrade performance or resource consumption at expected scale.
std-code-operational-readiness-03 - A reviewer SHOULD confirm a breaking change is intentional and its impact on consumers has been considered.
std-code-operational-readiness-04 - A reviewer SHOULD consider whether operational documentation, such as a runbook, needs updating to reflect the change.
std-code-operational-readiness-05 - A reviewer SHOULD consider whether a higher-risk change should be released behind a feature flag, enabling it to be disabled quickly or rolled out progressively.
std-code-operational-readiness-06
Related Standards
Implements These Principles
Review Feedback
Summary
Blocking feedback is resolved before merge, deferred advisory feedback is tracked, and a materially revised change is re-reviewed with its prior approval marked stale.
Standards
- A reviewer MUST distinguish feedback that must be resolved before approval (blocking feedback) from feedback that is advisory or optional.
std-code-review-feedback-01 - Advisory feedback deferred until after merge SHOULD be recorded in a tracking system so it is not lost.
std-code-review-feedback-02 - A change MUST NOT be merged while unresolved blocking feedback remains outstanding.
std-code-review-feedback-03 - A change materially revised after approval, such as a behaviour-changing commit or conflict resolution, MUST be re-reviewed.
std-code-review-feedback-04 - A change's prior approval SHOULD be marked stale after the change is materially revised.
std-code-review-feedback-05
Implements These Principles
Review Conduct
Summary
Review feedback stays specific enough to act on, and rigorous without becoming adversarial.
Standards
- Review feedback MUST be specific enough that the author understands both the concern and the change needed to resolve it.
std-code-review-conduct-01 - Review SHOULD remain rigorous and non-adversarial, with the purpose of improving the change and the shared codebase.
std-code-review-conduct-02
Implements These Principles
Review Turnaround
Summary
A review request is actioned within an agreed timeframe, or reassigned to a reviewer who can.
Standards
- A review request SHOULD be actioned within an agreed, reasonable timeframe appropriate to the repository or team.
std-code-review-turnaround-01 - A reviewer unable to review a request within its agreed timeframe SHOULD reassign or flag it so another reviewer can act on it.
std-code-review-turnaround-02
Implements These Principles
Emergency Change Review
Summary
An emergency change may merge through an expedited, auditable review path and receives risk-proportionate post-implementation review after the incident is resolved.
Standards
- A change MAY merge under an expedited review path only where normal review would materially increase operational or safety risk.
std-code-emergency-change-review-01 - A change MAY merge under an expedited review path only through an approved, auditable emergency process.
std-code-emergency-change-review-02 - Review MUST still be performed to the greatest extent practical before an emergency change merges.
std-code-emergency-change-review-03 - A change merged under expedited review SHOULD receive a post-implementation review once the incident is resolved, with any corrective follow-up identified and tracked.
std-code-emergency-change-review-04
Implements These Principles
Approval Records
Summary
An approval is recorded through the merge request mechanism, attributable to its reviewer and traceable to the change.
Standards
- Approval MUST be recorded through the repository's merge request review mechanism, attributable to the reviewer who granted it.
std-code-approval-records-01 - An approval record MUST remain traceable to the change it covers for as long as the change's history is retained.
std-code-approval-records-02