Skip to content
All posts

Open source · Practice

Reading a codebase you didn't write

A repeatable way to find your footing in an unfamiliar repository in an afternoon, from the entry point to the first change you can trust.

2 min read

Every open source contribution starts with the same feeling: 80,000 lines of code, a bug report, and no idea where to look. This is the process I use to get from that feeling to a change I trust, usually in an afternoon.

1. Run it before you read it

Clone the repository, follow the contributing guide exactly, and get the test suite passing on your machine. If that fails, you have found your first contribution: the guide is wrong.

Running the software also gives you a vocabulary. You will search for the words you see on screen long before you understand the architecture.

2. Find the entry point

Every program starts somewhere. For a CLI it is the command parser, for a server it is the router, for a library it is the exported API. Open that file and follow one real path all the way down, ignoring everything else.

# Where does the "runs list" command go?
rg "runs list" --type go
rg "func listRuns" --type go

Write the path down as a list of files. Mine for Corvid’s runs list was five files long, and four of them turned out to matter for every bug I fixed that year.

3. Read the tests for the area you are changing

Tests are the most honest documentation a project has. They show how the authors expected the code to be called, which inputs they worried about, and which bugs already happened once.

If the area has no tests, write one that reproduces the bug before touching anything else. It will be the most useful part of your pull request.

4. Read the history

git log -p on the file you are about to change answers the question every reviewer will ask: why is it like this?

git log --follow -p -- internal/runs/list.go

Half the strange code I have wanted to delete turned out to fix a bug from three years earlier. The commit message usually says which one.

5. Make the smallest change that proves you understand

Your first change in a new codebase should be small enough that a reviewer can check it in five minutes. Size is not the goal. Confidence is, both yours and theirs.

The short version

  • Run it, then read it.
  • Follow one path from the entry point and write it down.
  • Trust the tests and the history over the comments.
  • Ship something small, then something bigger.

Keep reading