User Tools

Site Tools


git-for-lieutenants

This is an old revision of the document!


This page contains an instructions and guidelines for lieutenants. Lieutenants are experianced developpers and maintainers, usually in charge of a specific subsystem of the project and they merge in changes from individual developpers and push to the reference (blessed) repository that everyone then clones from again.

:!: Remember: As Lieutenant you are responsible for the project, so you have to make sure, that the contributed work meets all requirements:

Push access to reference repository

Lieutenants should use SSH protocol to access the reference repository. To grant ssh access, you have to send your public ssh key(s) (see http://git-scm.com/book/en/Git-on-the-Server-Generating-Your-SSH-Public-Key for reference).

Lieutenants clone oofem repository using ssh protocol:

  git clone git@www.oofem.org:/data/git/oofem.git

Reference repository

On the reference repository, two main branches exist:

  • master - this branch is used for development.
  • stable - this branch is stable and should be in a state that allow a release at any time. Please do not merge any changes into this branch.

Individual developpers typically clone the main repository, create a topic branch, derived from master branch of the main repository and make their development there. Then they create a patch or patch series they are planning to contribute. Basically, the same procedure is followed by Lieutenants for their own development, except they do not have to send patches to themselfs.

The sequence looks basically like this:

# clone reference repo

$ git clone http://www.oofem.org/git/oofem.git oofem.git
# Note: when a repository is cloned, git automatically creates a master branch that tracks origin/master
$ cd oofem.git
# create a new brach for a new development
$ git checkout -b featureA
$ (work)
$ git commit
$ (work)
$ git commit

Now you have your commits that you want to send to the maintainers. It is strongly recommended to use rebase -i to squash your work down to a single commit, or rearrange the work in the commits to make the patch easier for the maintainer to review — see Git book for more information about interactive rebasing.

The user use git format-patch to generate the mbox-formatted files.

Applying Patches from E-mail

If you receive a patch over e-mail that you need to integrate into your project, you need to apply the patch in your topic branch to evaluate it. Please see detailed descption of this topic in Git book.

The Lieutenants of the Git project tends to namespace these branches as well — such as c_name/featureA, where c_name is short for the person who contributed the work. As you’ll remember, you can create the branch based off your master branch like this:

  #create a feature branch
  $ git branch c_name/featureA master
  # and to switch into this branch
  $ git checkout c_name/featureA
  

Or, if you want to also switch to it immediately, you can use the checkout -b option:

  $ git checkout -b c_name/featureA master

Now you’re ready to add contributed work into this topic branch and determine if you want to merge it into reference longer-term develop branch.

To apply a patch generated by format-patch, you use git am. f someone has e-mailed you the patch properly using git send-email, and you download that into an mbox format, then you can point git am to that mbox file, and it will start applying all the patches it sees. If you run a mail client that can save several e-mails out in mbox format, you can save entire patch series into a file and then use git am to apply them one at a time.

   $ git am 0001-limit-log-function.patch 
   Applying: add limit to log function
   
   

You can see that it applied cleanly and automatically created the new commit for you. The author information is taken from the e-mail’s From and Date headers, and the message of the commit is taken from the Subject and body (before the patch) of the e-mail.

It is possible that the patch won’t apply cleanly. Perhaps your main branch has diverged too far from the branch the patch was built from, or the patch depends on another patch you haven’t applied yet. In that case, the git am process will fail and ask you what you want to do:

 $ git am 0001-seeing-if-this-helps-the-gem.patch 
 Applying: seeing if this helps the gem
 error: patch failed: ticgit.gemspec:1
 error: ticgit.gemspec: patch does not apply
 Patch failed at 0001.
 When you have resolved this problem run "git am --resolved".
 If you would prefer to skip this patch, instead run "git am --skip".
 To restore the original branch and stop patching run "git am --abort".

This command puts conflict markers in any files it has issues with, much like a conflicted merge or rebase operation. You solve this issue much the same way — edit the file to resolve the conflict, stage the new file, and then run git am –resolved to continue to the next patch:

 $ (fix the file)
 $ git add ticgit.gemspec 
 $ git am --resolved
 Applying: seeing if this helps the gem

If you want Git to try a bit more intelligently to resolve the conflict, you can pass a -3 option to it, which makes Git attempt a three-way merge. This option isn’t on by default because it doesn’t work if the commit the patch says it was based on isn’t in your repository. If you do have that commit — if the patch was based on a public commit — then the -3 option is generally much smarter about applying a conflicting patch:

  $ git am -3 0001-seeing-if-this-helps-the-gem.patch 
  Applying: seeing if this helps the gem
  error: patch failed: ticgit.gemspec:1
  error: ticgit.gemspec: patch does not apply
  Using index info to reconstruct a base tree...
  Falling back to patching base and 3-way merge...
  No changes -- Patch already applied.

In this case, I was trying to apply a patch I had already applied. Without the -3 option, it looks like a conflict.

When all the patches for your topic are applied and committed into your branch, you can choose whether and how to integrate them into a develop reference branch.

For example, once you merged all patches to a master branch on a local machine, push the local master branch to the server via

 $ git push origin master

Merging workflow

In oofem project, we have two long-running branches, master and stable. stable is updated only when a very stable release is cut and all new code is integrated into the master branch. Each time you have a new topic branch to merge in, you merge it into master.

git-for-lieutenants.1355909669.txt.gz · Last modified: 2012/12/19 10:34 by milan