User:Roan Kattouw (WMF)/Topic branches

In this example we'll assume you want to create a topic branch called 'foo' based off 'test', and maintain the topic branch in Gerrit. If you base your branch off something else (e.g. another topic branch), you should be OK with replacing 'test' with your base branch throughout.

Creating a topic branch

In the Gerrit interface, go to Admin -> Projects -> operations/puppet -> Branches and create a new branch with the testlabs/ prefix. For 'initial revision', specify 'test'.

Create the topic branch locally:

$ git checkout -b foo test

Pushing to the topic branch

Push your commits to the remote testlabs/foo branch for review:

$ git push puppet foo:refs/for/testlabs/foo

Your commits are now awaiting review in Gerrit. They are not yet in the remote testlabs/foo branch until you review them and merge them in Gerrit (click Review, give a +2, click publish&submit).

Tracking the remote topic branch

You may find it useful to have a local copy of the remote testlabs/foo branch, which contains only those commits that were reviewed and merged through the Gerrit web UI. This is very easy to set up: if you have no local testlabs/foo branch yet, you can just check it out and git will automatically initialize it for you:

$ git checkout testlabs/foo
Branch testlabs/foo set up to track remote branch testlabs/foo from origin.
Switched to a new branch 'testlabs/foo'
$ 

You should use this branch in a read-only fashion. That is, you can use git pull to update it to the current state and use it to look at the state of the remote branch offline (you will also need this when merging back into test), but you should not modify the local testlabs/foo branch, and you should never push any such modifications. New commits should be pushed for review, then reviewed and merged into the testlabs/foo branch using the Gerrit web UI.

Merging the topic branch back into test

When merging back, you should only merge the remote testlabs/foo branch. You should never merge the local foo branch if it is not identical to testlabs/foo, and you should never, ever, rebase commits that have already been pushed to gerrit.

Make sure you have an up-to-date copy of testlabs/foo:

$ git checkout testlabs/foo
$ git pull

Now merge testlabs/foo into test locally:

$ git checkout test
$ git merge --no-ff testlabs/foo   # --no-ff ensures a merge commit is always created, even if the merge can be fast-forwarded

If there were conflicts:

$ vi conflicted.pp                 # Edit the file and fix the conflicts
$ git add conflicted.pp            # Tell git the conflicts in this file have been resolved
...                                # Repeat for any other conflicted files
$ git commit                       # Commit the merge

If there were NO conflicts, you have to amend your commit to make sure the Change-ID is added (this is a workaround for a bug):

$ git commit --amend               # Amend the commit, but save the commit message without changing anything

Verify the merge diff:

$ git diff HEAD^

Push the merge commit for review:

$ git push-for-review-test        # or git push puppet HEAD:refs/for/test if you don't have this alias set up

From here on out, you can follow the normal review -> merge to test -> merge to production workflow. Your merge will show up as a single changeset in Gerrit (because you only submitted the merge commit; this is why --no-ff is important) and will be reviewed, merged into test, and merged into production as a single commit, but it is still linked to your branch so accessing the individual revisions that were merged is easy.