Who will read the PR you sent?

A comment adds something another person has to read and possibly act on. Code contributions ask for a different kind of attention. When you send a pull request, a maintainer must understand your change in the context of a system they look after. The debugging and testing methods we have used throughout the book can help you make that work easier to assess.

Start with what debugging is. It is the search for the gap between what a person meant and what the machine does, and it needs a meaning to aim at. In someone else's codebase you do not know their meaning yet, so you cannot argue from it. Reproducing the behavior gives both of you something concrete to inspect.

Here is a small example. A project shows results in pages, and the function that counts pages looks like this. For this example, total is a nonnegative integer and per_page is a positive integer. Save the function in a disposable file called pagination_demo.py:

def page_count(total, per_page):
    return total // per_page

With 101 items and 10 per page it returns 10, so item 101 can never be reached. Before touching the code, write the report as if the maintainer had never seen the bug:

Steps:    create 101 items, request /items?page=11 with per_page=10
Expected: page 11 shows item 101
Actual:   404, the last page is 10
Version:  [the commit tested], [Python version], [dependency lockfile]

Expected and actual are the heart of it. A maintainer who reads only those two lines should know whether they agree it is a bug, and the steps alone should be enough to see it happen.

Now the test, which is where a lot of honest work goes wrong. I opened a pull request on LMCache, a KV cache layer for inference, with a test that was supposed to expose the disk-writing bug I was fixing. A reviewer ran it with the patch and without it. It passed both times. The supposedly misaligned memory address was still valid on that device, so the test never reached the defect. A different offset produced the useful comparison: failure before the patch, success after it.

That is the check worth doing before anyone else has to. A regression test has two jobs: fail on the old code and pass on the new code, with nothing else changed between the two runs.

Append this assertion to the file:

assert page_count(101, 10) == 11

Run python3 pagination_demo.py. It should stop with an assertion failure. Then replace the function with the fix below and run the same file again. A successful assertion prints nothing and the process exits successfully.

Read the failure message on the first run. A test that fails with an import error has not reproduced anything. In a real repository, compare the dependency lockfile too: if a dependency version moved between the two runs, you cannot tell whether your fix or the upgrade changed the result. Mocks are useful for isolating a dependency, but check where the fault lives. If the mock replaces the behavior under investigation, the test can miss the regression entirely.

The fix itself should be as small as the bug:

def page_count(total, per_page):
    return -(-total // per_page)

One line changed, one test added, and a description saying what, why, and how you checked. If the same diff also renames variables and reformats the file, the maintainer has to separate your fix from your preferences, which is exactly the reading you were trying to save them.

Sometimes the maintainer will still say you are wrong. On another project a maintainer told me my patch was wrong. I did not argue. I collected the output of the same fault from three separate projects and brought it back, and the patch changed. None of it came from knowing the code better than its author. It came from carrying the evidence so the person reading did not have to go and find it.

Ownership is not authorship. It is being able to produce evidence on demand, which is why a flood of unread pull requests is a real cost. Writing scaled and reading did not. Merging a diff you have not read moves the afternoon to whoever is awake when it breaks.

Before submitting, take the fix out and run the regression test again. If it still passes, strengthen the test before presenting it as evidence for that fix.