Whether collaborating on code, data, or prose text, there are lots of different strategies for using pull requests on GitHub. I once saw a post that outlined a handful of ways teams use pull requests, that seems to be subsequently lost forever, despite looking high and low. Here’s how I see pull requests used at GitHub:
Just a heads up
How it works: Create a pull request and immediately merge it yourself without others’ review.
When to use it: When you’re making a change so uncontroversial or straight forward that no review is required, but you want to let your teammates know that you’ve made the change. Dependency bumps are a good use case.
How it works: Submit a pull request with a minor change, wait a short period for a sniff-test review, and self merge.
When to use it: When you’ve got a small change, potentially in a part of the codebase outside your area of expertise, and you’d like someone with more experience to provide a quick before your merge the change.
Work in progress (WIP)
How it works: Prefix the pull request title with
WIP:. Optionally add emoji and “DO NOT MERGE” in bold if you’re ultra-paranoid.
When to use it: When you’ve started a new feature, document, or bug fix, that’s not quite ready for others to review, but you want to let your teammates know that you’re working on the feature. This can be used to prevent the duplication of effort, save work that you’ve started, or complement your team’s workflow.
How it works: Roughly spike out a feature by creating a proof of concept or rough outline that expressed your idea in its final form.
When to use it: When you want feedback on your general approach or the idea itself. Is this a dumb idea? Is there a better way to do this? The content of the pull request exists to convey the idea, and will likely not be the final implementation. This may start as a WIP and may end with a line-by-line review.
How it works: Submit a feature-complete pull request and cc relevant teams, asking for their review. Team members will comment line-by-line and re-review as you implement their changes.
When to use it: When you’re ready to the thing. It may have been started as a work in progress, or for early feedback, but you’ve made it clear that unless you hear otherwise, you’re going to hit merge.
Pull request to a pull request
How it works: You submit a pull request, that instead of requesting a merge into the
master branch, requests that its changes be merged into a branch that is the basis of another pull request.
When to use it: When you don’t have write access to the source repository (e.g. open source), and would like to make substantial changes to an existing pull request created by another user. For smaller changes, use line-by-line comments with the proposed code.
Interested in learning more about how GitHub works and what it’s like to be a GitHubber? Check out these popular posts on GitHub’s culture and communication patterns.
If you enjoyed this post, you might enjoy:
- 15 rules for communicating at GitHub
- Five best practices in open source: external engagement
- Towards a More Agile Government
- Twelve tips for growing communities around your open source project
- Eight things I wish I knew my first week at GitHub
- Ten ways to make a product great
- Why open source
- The seven habits of highly effective GitHubbers
- 19 reasons why technologists don't want to work at your government agency
- Four characteristics of modern collaboration tools
- Five best practices in open source: internal collaboration
Ben Balter is a Senior Technical Program Manager at GitHub, the world’s largest software development network. Previously, as the Senior Product Manager overseeing the platform’s Trust and Safety efforts, Ben shipped more than 500 features in support of community management, privacy, compliance, content moderation, product security, platform health, and open source workflows to ensure the GitHub community and platform remained safe, secure, and welcoming for all software developers. Before joining GitHub’s Product team, Ben served as GitHub’s Government Evangelist, leading the efforts to encourage more than 2,000 government organizations across 75 countries to adopt open source philosophies for code, data, and policy development. More about the author →