wiki:Policy/GitMaster

Using Git and Angband - a guide for the devteam

Setting up

Assuming your local repo has as its "origin" your own github repo, you'll need to add a new remote to track the official one: git remote add official git@github.com:angband/angband.git (this url assumes you are using ssh access and have configured your local ssh config accordingly). After a git fetch official you will then see the official/master, official/3.3-release, official/3.4-release, official/3.5-release, official/4.0-release and official/AngbandBase branches, as well as all the origin/ branches of your own github repo.

Make a local copy of the official/master branch (we'll call it master2, because your local "master" branch is tracking your origin/master):

$ git checkout official/master
$ git checkout -b master2

To keep this branch up-to-date:

$ git fetch official
$ git checkout master2
$ git merge official/master

Feature branches

To work on a feature:

  1. Branch from a stable commit (e.g. official/master)
  2. Develop on that branch and don't worry about keeping up
  3. When you're done, try to rebase your work on the latest master - if it doesn't work, don't worry, just back out
  4. Merge back into master

Avoid continually merging in the latest changes from upstream, because it makes it a lot harder to follow the change history when it comes to merge, and you may end up fixing the same merge conflicts many times. If you have a set of big changes to make, merge to master after each one, rather than trying to merge master into your branch after each one.

Merging

When you're done with your feature branch (we'll call it mybranch) and you're ready to merge, do:

$ git checkout master2
$ git pull official master
$ git merge --log -m "description of merge (e.g. Merge fizzix's vault refactor)" mybranch

The --log parameter appends a list of changes in that branch, which is useful when browsing history. The -m parameter just avoids the ugly (and often meaningless) default merge messages.

You may get merge conflicts, in which case, fix them and then commit. Make sure your local master2 branch compiles, and when it does, push to the official master with

$ git push official master

If the official master has changed since you checked out, you are unlucky and you should do the merge again or rebase. This way, your local master2 branch should always be strictly ahead of the official master branch.

Bugfixes

To fix a bug in the current release (currently 4.0.x)

  1. Branch from official/4.0-release
  2. Fix the bug on your new branch
  3. Rebase onto 4.0-release (it may not have moved, which makes it easy)
  4. Merge back into 4.0-release

N.B. When responding to a pull request, please check that the changes adhere to the CodingGuidelines before committing to master.

Last modified 21 months ago Last modified on 06/30/15 08:59:16