Skip to content
All posts

Open source · Career

My first pull request to a 20k star project

The issue I picked, the three versions of the patch, and the review comments that taught me more than the code did.

2 min read

Three years ago I had never contributed to a project bigger than a weekend library. Today I help maintain Corvid, a workflow engine with 23,817 stars. The path between those two points started with one small pull request, and almost everything I did wrong on it is worth writing down.

Picking the issue

I spent a week looking for the perfect first issue and found nothing. The good first issue label was either empty or full of issues that three other people had already claimed.

What worked was using the project for something real. I was running Corvid for a side project, and the CLI printed durations in milliseconds with no units. That was the whole bug. I opened an issue, described what I saw, and asked whether a fix would be welcome before writing it.

The best first issue is one you hit yourself, because you already understand why it matters.

A maintainer replied the same day and pointed me at the file that formatted output.

Three versions of the same patch

Version one changed the formatting function and nothing else. It was 11 lines, and it was rejected in the kindest possible way: the same function was used by the JSON output, and I had just changed a public format.

Version two added a separate formatter for humans. Better, but I had copied the logic instead of sharing it, and the reviewer asked me to look for the existing duration helper in the internal/units package.

Version three looked like this:

// FormatDuration renders a duration for people, not machines.
// JSON output keeps using raw milliseconds.
func FormatDuration(d time.Duration) string {
	if d < time.Second {
		return fmt.Sprintf("%dms", d.Milliseconds())
	}
	return units.Round(d, 2).String()
}

It also included a table test with seven cases, including zero and negative durations, which the reviewer had not asked for. That pull request was merged four days after I opened the issue.

What the review actually taught me

  • Public formats are promises. Anything a script might parse is an API, even if nobody wrote it down.
  • Search before you write. Large projects have already solved most small problems once. Finding that solution is part of the work.
  • Tests are a courtesy. They show the maintainer you understand the edges, which makes the next review faster.

After the first one

The second pull request took half as long. By the tenth, I was reviewing other people’s changes. If you are looking for a place to start, use the tools you depend on until one of them annoys you, then ask whether a fix would be welcome.

Keep reading