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 git:

origin: The repository to which you publish proposed changes
upstream: The repository from which you receive ongoing development, and which will +receive your changes.

One-time setup

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 upstream and +pretending its push URL is UPSTREAM-URL below. In real life, the URL will +often be something like git@github.com:someguy/project.git.

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 +I'll abbreviate ORIGIN-URL, for 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 origin:

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
+

Feature process

Do these things for each feature you work on. To switch features, just use +git checkout my-feature.

Create a new feature branch locally

We use upstream's 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
+

Do work

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 +for my-feature.

Integrating feedback

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 +branch:

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.

+ + + +

+ + +comments powered by Disqus +

+ + + + + +