21 July 2013

How to make pull requests on GitHub or BitBucket

Github and Bitbucket make it very easy to submit pull requests; probably too easy, in fact. The temptation to just fork somebody's repo, fix the obvious mistake and submit a pull request is quite strong. But that's not how you're supposed to work! So this is basically a dummy's guide to mark this procedure into my brain.

A pull requests marries the entire branch to the one you're targeting; if you keep making changes here and there, a pull request will include all these new changes, regardless of when you originally opened it. It makes your request basically un-mergeable by upstream repositories, in most cases.

So the real procedure is:

  1. Fork the upstream repository. Now you have your own master branch. Clone it locally as usual.
  2. Create a new branch, either via web or (easier) from the command line with git branch FixBugBranch && git checkout -b FixBugBranch. 
  3. Make your changes on this FixBugBranch. Make only the minimum amount of changes necessary to fix a specific issue, then commit and push.
  4. On GitHub, create a pull request from FixBugBranch towards the original repository
  5. When/if your pull request is accepted upstream, you can delete FixBugBranch.
If you want to make further changes, you can either create a further branch from FixBugBranch, or create and merge a pull request from FixBugBranch into your master. The important thing is that you don't touch FixBugBranch anymore, so that upstream maintainers won't receive all your extra commits but only ones relevant to the particular bug you raised. 
at

3 comments:

  1. Giulio Piancastelli23/7/13 22:04

    git checkout -b FixBugBranch, thank you very much.

    ReplyDelete
  2. Anonymous24/5/14 20:55

    This seems to make sense if you have write access to the repo. What if I don't have write access? Am I missing something?

    (What prevents trolls from branch-bombing?)

    ReplyDelete
  3. toyg25/5/14 10:35

    What do you mean by "branch-bombing"?

    Once you fork, the forked repo is yours -- it's how distributed VCS works, they make whole copies. If you want to create 123456 branches on it, it's your problem, nobody cares. To clarify, the branch is created *on your own repo*, not on the original one.

    People are only "affected" when you issue a pull request, but nobody is in any way forced to accept your requests -- more often than not, in fact, they will be either ignored or deleted if you're proposing something the original owner does not agree with. If you issue 123456 pull requests, chances are that you will be flagged and GitHub / Bitbucket will take action and ban you.

    ReplyDelete