User:Roan Kattouw (WMF)/Branching guide

A few branching and merging patterns explained. TODO: so far it's only one.

Local branch for every change

What and why

It is recommended that you don't base unrelated or independent changes off each other, but base each change off the HEAD of the remote test branch instead:

WRONG:   test -- A -- B -- C

               A
RIGHT:       /
         test -- B
             \
               C

Advantages are:

It will be possible to merge B individually, without merging A. If B depends on A and you try to merge B before A, Gerrit will complain
It will be possible to abandon A and keep B around, or even merge B
You will notice more quickly if your changes don't turn out to be independent after all :)

Of course if A, B and C are related or even dependent on each other, basing them off each other (i.e. using the "WRONG" pattern above) is the right thing to do.

How

When using this pattern you should keep your local 'test' branch clean. That is to say, your local test branch should mirror the remote test branch exactly and should not contain any commits that haven't been reviewed and merged. In practice this means that your new commits shouldn't be in the test branch.

$ git checkout -b fixfileperms origin/test    # Create a new branch called 'fixfileperms' based off the remote test branch, and switch to it
work work work
$ git commit -a -m "Fix file permissions"
$ git push-for-review-test

If you mistakenly commit something to test directly and want to clean it up, do this:

$ git checkout test                    # Switch to the 'test' branch
$ git commit -a -m "Blah blah"         # Mistakenly commit something to 'test'
$ git branch oops                      # Create a new branch called 'oops', which will contain your new commits
$ git reset --hard origin/test         # Reset the local 'test' branch to point to the head of the remote 'test' branch and DISCARD ALL LOCAL CHANGES
$ git pull                             # Update the local 'test' branch from the remote

You can also have small feature branches this way by simply committing multiple revisions to the same branch. When you push, each of your revisions will be pushed separately.