Journal Archives About Books Talks
journal

Patches speak louder than words

Fundamentally, issue trackers track two types of things: features you want to build and bugs you need to fix. The next time you decide to add an issue to a GitHub repository, consider sending a pull request instead.

Since pull requests are issues with code attached, you may be thinking "wait why would I start with code, shouldn't we talk about this first?"

Maybe. For many situations, starting with a pull request can often create a more effective discussion of the change.

Show rather than tell

A pull request can demonstrate behavior and get everyone in a shared context in order to start a discussion. You don't have to wait until a branch is production-ready to open a pull request.

For bugs, start with a failing test. In our age of cloud-based continuous integration services, a failing test can quickly demonstrate a bug without requiring anyone to pull down your branch locally to run the test suite.

For features, you might start with a UI mockup. Fake the behavior you'd like to add and get agreement on how it should work before you think about how to implement the new feature.

Clarify your thinking

Some changes are an effort to pay down technical debt. They're often refactorings that the team would like to do "someday," but nobody acts because no one is quite sure how much effort it involves.

Spike it in a branch and open a pull request. These spikes are a great way to make code changes and let the test suite tell you how much carnage ensues.

Put some skin in the game

Opening a pull request requires more effort than just opening an issue. Pull requests show how much you care. It's easy to complain about a bug or wish out loud for a new feature. A pull request says you believe in the change so strongly that you're willing to contribute to a solution.

Learn to fish

Pull requests help maintainers scale. Reviewing and merging patches takes less effort than making every change themselves. Pull requests are an effective way to bring along new maintainers into a project, demonstrating both skill and desire.

Looking to get started in open source? Start contributing where others are complaining.

Don't get too attached

It's easy to become emotionally involved with the code or words we write. Just because there's code attached doesn't mean you should be. Don't be afraid to let go of code in a branch. Some code exists just to prove something won't work. Often, the questions surfaced are more valuable than the code itself.

I've probably learned the most from the pull requests that were never merged.

# Posted on