git-recipes
This page is a collection of recipes for using git when contributing to sardana. It is a complement to the [SEP7] from a practical/informal point of view.
The recipes are organised according to the diferent roles in the sardana community (contributor, integration manager, SepX 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 [SEP7]. Just check the references provided for more options.
Contributors to the sardana 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 sardana for your local repo
- you know the git basics (clone, checkout, add, commit, pull, push,...)
- you have read [SEP7]
Clone the official repository
git clone git://git.code.sf.net/p/sardana/sardana.git sardana
See the git page of sardana-core 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)
~/sardana$ git config -l user.name=johndoe user.email=johndoe@example.com sendemail.smtpserver=smtp.example.com sendemail.to=sardana-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 [SEP7]):
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 sardana-devel@lists.sourceforge.net :
#make sure you are still in the bug-123 branch... git checkout bug-123 #rebase to make sure that your patch can be applied to the latest origin/develop #(if this step causes conflicts, resolve them before sending the patch) git rebase origin/develop #prepare the patch(es)... git format-patch -M origin/develop #one or more .patch files are created... Now send them: # consider adding "--compose" if there are many patches # and consider using "--in-reply-to" if you are resubmitting a patch git send-email *.patch
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/sardana.
Just push your branch there:
# add your public repo to your remotes git remote add johndoe ssh://johndoe@git.code.sf.net/u/johndoe/sardana # 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/sardana # (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/sardana/sardana.git sardana
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/sardana/sardana.git git remote set-url --push origin ssh://johndoe@git.code.sf.net/p/sardana/sardana.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 sardana-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 (if this fails, you may try passing the "-3" parameter) 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 [SEP7]
- 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 solve the conflicts (you may as well request the contributor to solve them and resubmit).
SepX 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/sepX 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.