oofem-wiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

This page contains an instructions and guidelines for lieutenants. Lieutenants are experienced developers and maintainers, usually in charge of a specific subsystem of the project and they merge in changes from individual developers 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:
  * [[coding-conventions|oofem coding conventions]] have been followed,
  * sufficient documentation and internal tests provided

====== 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 developers 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 themselves.**

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 description of this topic in [[http://git-scm.com/book/en/Distributed-Git-Maintaining-a-Project|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.

To merge changes made in c_name/featureA branch into the master branch, switch to master branch first and then merge c_name/featureA branch into it

$ git checkout master
   $ git merge c_name/featureA

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

Finally, the c_name/featureA branch can be deleted

$ git branch -d c_name/featureA
====== 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''.

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International