Reading the code and proposing a change

A small change is a good opportunity to put this reading into practice. Let us begin with behaviour we can observe.

Notation conventions

Function names, types, commands, options and filenames appear in monospace, for example describe, wf test or main.cpp. Italics introduce a term at its definition. Code blocks give the fragments to enter; the preceding text states their location and prerequisites.

Starting with a specific problem

A contribution often starts with something modest: a call failing unexpectedly, an unclear diagnostic or a case not yet covered by tests. Let us describe what we did and the result we expected. That gives us a firmer starting point than a general rearrangement of files.

We can then find the relevant guide and architecture decision, followed by nearby tests. Repository instructions suggest beginning with ADRs 001, 002 and 012 before those for the affected area.

Sometimes the desired behaviour requires changing an accepted decision. There is no reason to hide that change: explain the problem, propose the revision and describe its consequences for existing code. An idea still under proposal remains distinct from what the program already does.

Making the defect visible

If a decoder accepts an array of the wrong size, we can demonstrate that without opening a window. A small Catch2 test will give those exact bytes to the relevant code. It will then tell us whether the fix handles that case.

For a completion race, we shall instead try to impose interesting orderings with deterministic doubles. For a CMake integration problem, a small consuming project may reveal what internal tests cannot see.

Finally, a bridge change needs checking in a real browser. The precise test helps us understand the defect; the complete path checks that both ends still work together.

Widening the checks

Once the precise test passes, verification is not yet finished. A change can fix one case and disturb another. Let us therefore build in a separate directory, with CEF disabled and WEBFRONT_ENABLE_TESTING=ON, then run CTest.

The fast label makes intermediate checks convenient. Before finishing, repository instructions require the full suite. Changes to the bridge, engine lifecycle, modules or Jasmine resources also require the browser tests listed in AGENTS.md.

On Linux, the CEF path uses Xvfb; the build includes webtest, developer_integration and webfront-wf. Dependencies are provisioned at configuration so that tests need not obtain them from the public network while running.

Leaving a change that can be understood

Now let us read the diff as though we had not taken part in the work. Is the problem still recognisable? Does the test show why the change is needed? Can we explain who owns the data and what happens on failure?

Documents belong in this review too. A changed command needs its guide updated; a removed or added limitation needs explaining. The changelog records deliveries, project status describes current paths and ADRs retain the reasons for decisions.

The next developer will not have our conversation or remember our experiments. The sources, test and explanation should let that reader recover the reasoning and repeat the checks.

Check your understanding

What does a test that first demonstrates a defect provide?

Read the source documentation ↗