wiki:Policy/GitMaster

Version 4 (modified by takkaria, 8 years ago) (diff)

remove blocks of text and replace with terminal command blocks

Using Git and Angband

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/staging and official/integration branches, as well as all the origin/ branches of your own github repo.

Make a local copy of the official/staging branch:

$ git checkout official/staging
$ git checkout -b staging

To keep this branch up-to-date:

$ git fetch official
$ git checkout staging
$ git merge official/staging

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. Merge to staging when you're done

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 staging after each one, rather than trying to merge staging 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 staging
$ git pull official staging
$ git merge --log -m "description of merge (e.g. Merge fizzix's vault refactor)"

The --log paramater appends a list of changes in that branch, which is useful when browsing history. The -m paramater 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 staging branch compiles, and when it does, push to the official staging with

$ git push official staging

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

Pushing to master

Every now and again someone pushes from staging to master. Ideally, this is after some amount of testing of the staging branch and ideally is not done by the person who pushed the changes to staging in the first place. To propagate the changes (assuming your staging branch is up-to-date):

$ git checkout staging
$ git push official staging:master

The dev team is now big enough that we should resist propagating our own staged changes except in emergencies.

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