git-recipes

[OBSOLETE] These recipes are superseded by the new Pull-Request based workflow described in TEP16

This page is a collection of recipes for using git when contributing to taurus. It is a complement to the [TEP7] from a practical/informal point of view.

The recipes are organised according to the diferent roles in the taurus community (contributor, integration manager, TEPx lieutenant, ...)

IMPORTANT: these examples are not meant to be exaustive or exclusive. Many things could be done in alternative ways, depending on your system and/or preferences. Feel free to use your own ways as long as you follow the conventions of [TEP7]. Just check the references provided for more options.

Contributors to the taurus core repository

Assumptions:

• you have a sourceforge account (I use johndoe in these examples)
• you have git installed (I use git 1.8 in these examples)
• you will use the name taurus for your local repo
• you know the git basics (clone, checkout, add, commit, pull, push,...)
• you have read [TEP7]

Clone the official repository

git clone git://git.code.sf.net/p/tauruslib/taurus.git taurus

See the git page of taurus for more options.

Set up git format-patch and git send-email

Make sure that the following git settings are configured (see git config --help)

~/taurus$ git config -l
user.name=johndoe
user.email=johndoe@example.com
sendemail.smtpserver=smtp.example.com
sendemail.to=tauruslib-devel@lists.sourceforge.net
sendemail.from=johndoe@example.com
sendemail.confirm=always
push.default=simple

Of course, substitute the urls and johndoe data for your own.
Also, your own system configuration may require different type of configuration for being able to use git send-email. See this for other examples.

Work on a feature branch (e.g. to contribute a patch to a bug-123)

Create a new feature branch (see Naming convention for feature branches from [TEP7]):

git checkout -b bug-123 origin/develop

Work on it as usual, making commits to it. Remember to format your commit messages properly.

Once finished, submit your contribution as a patch to tauruslib-devel@lists.sourceforge.net :

#make sure you are still in the bug-123 branch...
git checkout bug-123
#optionally, you may rebase to ensure that you patch against the latest origin/develop
git rebase origin/develop
#prepare the patch(es)...
git format-patch -M origin/develop
#one or more .patch files are created... Now send them:
git send-email *.patch

Also, it will help your patch to be more easily integrated if before sending the patch, you check that your branch can be merged without conflicts with the current state of the official develop branch:

#create a temporary branch out of your feature branch, just for this test
git checkout -b mergetest-123 bug-123 
#try to merge it with the official develop branch
git merge origin/develop
#If there are conflicts, try to fix them before creating/sending the patch
#After finishing, you can remove the temporary  branch
git branch -d mergetest-123

Once your patch is sent and accepted, you can delete the bug-123 branch, since its commits will be already integrated in origin/develop.

Read this for more info on contributing via patches.

Collaborating with other people on a feature

If you want to collaborate with more people on a given feature (e.g., feature-321), one possibility is doing so in a public forked repo:

Case 1: you want to set your own public repo.

Sourceforge provides easy forking of the official repo. Once you fork, you get a repo called something like git.code.sf.net/u/johndoe/taurus.

Just push your branch there:

# add your public repo to your remotes
git remote add johndoe ssh://johndoe@git.code.sf.net/u/johndoe/taurus
# Push your feature-321 branch there
git push -u johndoe feature-321

Now and let other people pull from your fork (and maybe even push to it). When the moment comes, you can contribute the changes just as usual.

Case 2: a public repo with the feature branch already exists

Alternatively, if some other user (e.g. jane) has already published the branch in which you want to colaborate, you just need to check it out:

# add jane's public repo to your remotes 
# (If you have RW access, you can prepend "ssh://johndoe@" to the git url)
git remote add jane git.code.sf.net/u/jane/taurus
# (you may need to run "git remote update" before checking out)
# now checkout the feature-321 branch from her repo
git checkout -b feature-321 jane/feature-321

In both cases:
To update your local branch with changes from the public repo, you just do the usual:

git checkout feature-321
git pull 

Integration Managers

Make sure that you have write access to the official repo

Either clone the repo with write access:

git clone ssh://johndoe@git.code.sf.net/p/tauruslib/taurus.git taurus

Or if you want to reuse a previous read-only cloned repo, change the url to ssh for your origin remote:

git remote set-url origin  ssh://johndoe@git.code.sf.net/p/tauruslib/taurus.git
git remote set-url --push origin  ssh://johndoe@git.code.sf.net/p/tauruslib/taurus.git

You also want to make sure that develop and master track their origin counterparts

git branch --set-upstream-to=origin/develop develop
git branch --set-upstream-to=origin/master master

Apply a submitted patch

Assumption: the contributed patch(es) are stored in a mbox file (or a maildir folder) named foo.patch

The patches are sent to the taurus-devel mailing list. How you manage to get the patch email(s) into foo.patch depends heavily on your email reader. In some cases, you may need to "save as..." the patch email(s). In my case, I use kmail, which can work natively with mbox and maildir formats, so I just created a mbox folder for "patches_to_apply" where I copy the patch(es) I am integrating at the moment. Then I use its location wherever foo.patch is used in the examples.

So, let's assume that we have the patch(es) for fixing the bug with track number 123 downloaded to foo.patch:

# create a branch from origin/develop for testing the patch (see note 1 below)
git checkout -b bug-123 origin/develop
# apply the patches 
git am -i foo.patch

At this point, if the patch does not apply nicely, you may either fix the conflicts or ask the contributor to resubmit the patch.
If the patch applies nicely, then do whatever tests you need to be satisfied that the patch does what it is supposed to do and that it does not break anything else. Then you just need to merge into develop and push:

# change to your local develop branch and update it
git checkout develop
git pull
# merge bug-123 into develop
git merge --no-ff bug-123
# If the merge was ok  (see note 2 below), push the changes to origin
git push origin develop
# You can now delete the branch bug-123
git branch -d bug-123

And now just notify the list that you applied the patch and close the ticket related to bug-123

• Note 1: when creating the branch name, you must follow the Naming convention for feature branches from [TEP7]
• Note 2: it is possible that something has changed in origin/develop between the moment when you created the bug-123 branch and the moment when you merge and push your local develop, so you potentially you may need to

TEPx Integration Lieutenants

Integration lieutenants should follow mostly the same steps as the Integration Managers (see above).

The main difference is that they must work with the origin/tepX branch instead of origin/develop.

Release Managers

During a release, most instructions for Integration Managers apply, but adapting them according to the instructions from http://nvie.com/posts/a-successful-git-branching-model for release and hotfix branches.