Life With Pull Requests
I've been party to a number of discussions with folks contributing to pull-request-based projects on Github (and other hosts, but mostly Github). Because of Git's innate flexibility, there are lots of ways to work with pull requests. Here's mine.
I use a couple of naming conventions here that are not stock
- The repository to which you publish proposed changes
- The repository from which you receive ongoing development, and which will receive your changes.
Do these things once, when starting out on a project. Keep the results around for later.
I'll be referring to the original project repository as
pretending its push URL is
UPSTREAM-URL below. In real life, the URL will
often be something like
Fork the project
Use the repo manager's forking tool to create a copy of the project in your own namespace. This generally creates your copy with a bunch of useless tat; feel free to ignore all of this, as the only purpose of this copy is to provide somewhere for you to publish your changes.
We'll be calling this repository
origin later. Assume it has a URL, which
git push to use.
(You can leave this step for later, but if you know you're going to do it, why not get it out of the way?)
Clone the project and configure it
You'll need a clone locally to do work in. Create one from
git clone ORIGIN-URL some-local-name
While you're here,
cd into it and add the original project as a remote:
cd some-local-name git remote add upstream UPSTREAM-URL
Do these things for each feature you work on. To switch features, just use
git checkout my-feature.
Create a new feature branch locally
master branch here, so that your feature includes all of
upstream's state initially. We also need to make sure our local cache of
upstream's state is correct:
git fetch upstream git checkout upstream/master -b my-feature
If you need my help here, stop now.
Integrate upstream changes
If you find yourself needing something that's been added upstream, use rebase to integrate it to avoid littering your feature branch with “meaningless” merge commits.
git checkout my-feature git fetch upstream git rebase upstream/master
Publish your branch
When you're “done,” publish your branch to your personal repository:
git push origin my-feature
Then visit your copy in your repo manager's web UI and create a pull request
Very likely, your proposed changes will need work. If you use history-editing
to integrate feedback, you will need to use
--force when updating the
git push --force origin my-feature
This is safe provided two things are true:
- The branch has not yet been merged to the upstream repo.
- You are only force-pushing to your fork, not to the upstream repo.
Generally, no other users will have work based on your pull request, so force-pushing history won't cause problems.