Make a Software Change Easy to Review

Describe the problem and intended behaviour

A review starts with understanding why the change exists. Explain the trigger, what currently happens and what the user should experience afterwards. Keep the description specific enough for a reviewer to recognise whether the change addresses the problem.

In this fictional exercise, an enquiry form accepts a phone number but does not make clear which country code applies. The proposed change adds a selector and validates the combination. This example does not describe a live patch to apply.

Keep the change understandable

Identify the affected part of the application and relevant dependencies. Separate necessary behaviour changes from incidental formatting or unrelated work. A focused change can be easier to assess, but its wider effects still need consideration.

For the fictional form, explain whether stored records or existing integrations are affected. Do not assume that a field displayed correctly in the browser is also read correctly by the server. Include the mapping that the reviewer needs to understand the behaviour.

Provide useful validation evidence

Describe the normal path, missing-input behaviour and relevant existing behaviour checked. Record the environment and any limits of the checks. A list of passed commands does not by itself explain what user behaviour was verified.

For the practice example, test the selected country with a suitable fictional number and then test a missing selection. Explain what was expected and what was observed. Keep personal contact details out of public examples.

Respond to the review

Ask the reviewer to examine the final change and the evidence. Resolve questions about behaviour and update the description when the implementation changes. An approval should relate to the version that will actually be introduced.

GitHub supports comments and review decisions on pull requests. Use the official guide for platform steps. Practice by writing a short change description with the problem, result, affected area and validation. Ask a colleague to identify what remains uncertain.

Source and practice note

GitHub documentation provides the background on reviewing proposed changes. Examples and exercises are original RDE material using fictional situations.

Read the official guidance

Cover image: AI-generated illustrative scene created specifically for this resource.