Editorial starter example. Original guide created for the Devex launch; not research, a user testimonial, or a report of community activity.

A tidy change can still solve the wrong problem. Before reviewing style, write one sentence describing what the user should experience differently and how you will know it happened.

1. Start with the request

  • What action triggers the behavior?
  • What happened before the change, and what should happen afterwards?
  • Is the fix on the path that actually runs, or in a similar function that is not used?

Reproduce the issue before the fix where possible. When reproduction is unavailable, say so and distinguish evidence from a hypothesis.

2. Read the boundaries

Consider empty input, missing values, permissions, external service failures, and retries. Check whether an action can occur twice and what happens when a response arrives late. Every change does not need to solve every scenario, but it should respect the existing system’s contract.

3. Compare the explanation with the code

A convincing explanation is not evidence. Confirm that the changed file is loaded, configuration is read in the right place, and the result reaches the interface. Examine new dependencies or broad changes that were unnecessary for the fix.

4. Look for a test that can fail

A useful test would detect the incorrect behavior. Choose a successful path and a boundary case that matter to the user. If the change affects permissions, also test who must not succeed. Record what you ran and what remains untested.

5. Think about release and recovery

Does this require a data change, configuration, or an enablement flag? Can you return to the previous version without losing data? Define a simple success signal and a failure signal after release. A passing local test alone is not a reason to ship.

A short change-description template

Problem: [action and incorrect result]
Change: [new behavior]
Checked: [scenario + environment + result]
Not checked: [relevant gap]
Release and recovery: [step or limitation]

Discuss: Which test on your team caught a mistake that was hard to spot by reading code alone?