wiki:GitUsage/PullRequest

Version 1 (modified by magnate, 8 years ago) (diff)

First draft

Offering your contribution to Angband

When you've fixed a bug or implemented a new feature, please let us know. The preferred way to do this is to submit a pull request on github. To do this, you will need to have a github account and a repository "forked" from the offical angband repository, as described on the GitUsage page. We will call the repository "yourfork" and the branch with the bugfix or new feature "yourbranch".

  1. When you've finished and tested your work, publish it to github using git push origin yourbranch. Don't forget to rebase and fix any conflicts before pushing if necessary (git fetch official; git rebase official/master) - incorporating your work is much easier if it applies cleanly to the official/master branch.

N.B. Please make sure that yourbranch contains only commits you want merged to the official repository. If you have not kept your branches separate and there are commits relating to local changes or other work in yourbranch, things will get messy. To solve this, create a copy of master (git checkout official/master; git checkout -b yourbranch2) and cherry-pick the commits you actually want to offer up. (This method can also be used to avoid rebase conflicts, or at least isolate which commits are causing them.)

  1. Go to your github account in your browser and click on your fork. Don't forget to click the Branches tab and make sure you're looking at the right branch (github will always default to the master branch). Note that if you created yourbranch2 as described above, in order to tidy it up and offer only the right commits, then this is the one you need to look at.
  1. Click the "Pull Request" button, which is up near the top-right (just below the Search box). If you don't get a screen inviting you to write a description of the pull request, something has gone wrong (maybe you were not looking at the right branch, or your push didn't work).
  1. Write a description of what you're offering in the pull request. Please include details of any remaining issues (e.g. dependent on other tasks) or further related work you intend to do. Also, please include the ticket number(s) of any trac tickets that the request addresses (even if only partially).
  1. Click the "Send Pull Request" button, but don't stop there. Please go to each of the tickets you noted in 4 above, change the status to Pending and put a link to your pull request in each. It will be of the form http://github.com/angband/angband/pull/XXX, where XXX is the number of your pull request.

After you've issued the pull request

Often you'll think of some important fix or change after you've submitted a pull request. Don't worry - github handles this very cleanly. Just commit your additional changes to the branch from which you issued the pull request (i.e. from yourbranch, or from yourbranch2 if you had to cherry-pick and tidy it up), and push again. Github will automatically add those commits to the pull request.

Please note, though, that you cannot rebase after submitting a pull request. But that's not really your problem - once you've submitted the request, it's the devteam's job to review and merge it as soon as we can. If we merge something else first, we'll fix any merge conflicts when we merge yours.