Standard for Public Code

Require review of contributions

Requirements

  • All contributions that are accepted or committed to release versions of the codebase MUST be reviewed by another contributor
  • Review MUST include source, policy, tests and documentation
  • Reviewers MUST provide feedback on all decisions made and the implementation in the review
  • Contributions SHOULD conform to the standards, architecture and decisions set out in the codebase in order to pass review
  • Review SHOULD include executing running both the code and the tests of the codebase
  • Contributions SHOULD be reviewed by someone in a different context than the contributor
  • Version control systems SHOULD not accept non-reviewed contributions in release versions
  • Reviews SHOULD happen within two business days
  • Reviews MAY be performed by multiple reviewers

Why this is important

  • Increases codebase quality
  • Reduces security as well as operational risks
  • Creates a culture of making every contribution great
  • Catches the most obvious mistakes that could happen
  • Gives contributors the security that their contributions are only accepted if they really add value and provide a guaranteed point for feedback or collaborative improvement

What this does not do

  • Guarantee the right solution to a problem
  • Mean that reviewers are liable
  • Absolve a contributor from writing documentation and tests
  • Provide you with the right reviewers

How to test

  • Every commit in the history has been reviewed by a different contributor in a different context

Policy makers: what you need to do

  • Institute a ‘four eyes’ policy where everything, not just code, should be reviewed
  • Use a version control system or methodology that enables review and feedback

Management: what you need to do

  • Make delivering great code a shared objective
  • Make sure writing and reviewing contributions to source, policy, documentation and tests are considered equally valuable
  • Create a culture where all contributions are welcome and everyone is empowered to review them
  • Make sure no contributor is ever alone in contributing to a project

Developers and designers: what you need to do

  • Find other contributors on the project you would like to review your work, in your organization or outside of it
  • Look often at the listings of requests for code review and try to review others’ contributions as much as possible

Further reading