Responsible systems

Make a proposed change easy to inspect

Editorial edition · 16 November 2026

The idea

A reviewer needs to understand the resulting behaviour, not reconstruct a long conversation. A reviewable change describes the current problem, the proposed outcome and how the result was checked. Smaller, coherent changes are easier to assess and reverse.

Design choice

Show the affected scope and an example of the behaviour before and after. Include meaningful verification results and known limits. Keep unrelated cleanup outside the change when it would obscure what the reviewer is approving.

Worked example

A parser change includes one previously rejected valid input, its new result and a regression check for invalid input. The reviewer can evaluate the contract directly.

Before you ship

  • Describe concrete before-and-after behaviour
  • Keep scope coherent
  • Show relevant verification evidence

Examples are illustrative. Adapt the checks to your own environment.

Further reading

W3C provenance overview

Search the library