Version 3 (modified by magnate, 9 years ago) (diff)

More clarity on new branches

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". We assume that you have called your remote of the official repo "official", but if you are offering a contribution to v4 rather than V, you have probably called it something sensible like "v4".

  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. Note that you must rebase before pushing, as rebase changes the commit IDs - this doesn't matter at all if the only place they exist is in your local repo.

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.) From yourbranch2 you can use git rebase -i yourbranch as a sort of batch cherry-pick mechanism: it offers you a list of all the commits which are in yourbranch but not in master, and you can choose the ones to add. Note that rebase will say "nothing to do" if yourbranch will apply cleanly (i.e. fast-forward merge) to master - so this is a good test.

  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, 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.

After your work is merged, please don't continue working on that branch. Even if you're continuing development of the same feature, please fetch from official/master and start a new branch from there for your next pull request (there is no limit to the number of branches you can make). If for any reason you don't want to do this, then you must rebase your branch on official/master before pushing and offering up your next pull request. You should use rebase instead of merging from official/master, to avoid a proliferation of merge commits.

So the ideal loop is: {{{1. git fetch official/master

  1. git checkout official/master
  2. git checkout -b newbranch
  3. ... do your work in newbranch ...
  4. git fetch official/master again (to see if it has updated while you were working)

5b. (if it has) git rebase official/master (and fix any conflicts)

  1. git push origin newbranch
  2. Go to github and open pull request
  3. Go to trac and update any tickets
  4. Wait for pull request to be merged (you can push more commits while waiting)
  5. Go back to 1. and start again}}}