Git

From OTBWiki
Revision as of 14:51, 12 September 2017 by Manuel.grizonnet (Talk | contribs) (→‎If you have a Pull request on github.com/orfeotoolbox/OTB)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Useful Command

System Setup

First step is, of course, check that git is installed on your system :

  • For Linux users: check your usual package manager (apt-get, aptitude, yum, ...)
  • For MacOSX users: check on MacPorts, there should be an available port for your OSX version
  • For Windows users: check msysgit, some people have made a guide to setup this tool. There is also TortoiseGit available on Windows.

Access to repositories via HTTPS

The repositories are located on OTB server : git.orfeo-toolbox.org

When connecting to a server, git performs a certificate verification. This step may fail so you will have to setup the certificate manually :

  • Get the SSL certificate of git.orfeo-toolbox.org and store it locally, for instance in /home/user/.cert/git.orfeo-toolbox.org
  • (you can check the SHA1 fingerprint to compare two certificates)
  • Add this certificate to your git configuration. Discussion on otb-developers
 $ git config --global http.sslCAInfo /home/user/.cert/git.orfeo-toolbox.org

The command to clone a repository using the HTTPS access is : 

 $ git clone https://git@git.orfeo-toolbox.org/git/<repository>

From this clone, you will not be able to push commits to the server (because the default user git is not allowed to). If you have an account on the server, you may use your real login : 

 $ git clone https://your_login@git.orfeo-toolbox.org/git/<repository>

Access to repositories via SSH

The SSH protocol can also be used to access the repositories, but the link is slightly different : 

 $ git clone ssh://git@git.orfeo-toolbox.org/<repository>

Here, the login is always 'git' but the server will identify you based on your public SSH key. The server has a set of known public keys for registered users, so this access type cannot be used for an anonymous access.

Using git

Visual help for git commands here

Beware : some commands have a different behaviour between Git and Mercurial. For instance :

  • pull
    • in Mercurial : get latest commits from server into local repository
    • in Git : get latest commits from server (git fetch) AND merge them into your current branch (git merge)

When you want to synchronize your local branch with the corresponding remote branch on official server, there are 3 cases :

  • you have un-pushed commits in your local branch but the remote branch has not changed : you can directly use git push
  • your local branch is the same as the corresponding remote-tracking branch (no local commits), but the remote branch has moved : you can use git pull (since no merge is needed, your local branch will be updated as a fast-forward)
  • your local branch and the remote branch have diverged : you have local commits un-pushed, and the remote branch has moved. You may first use git fetch to get the new commits from remote branch, then you can choose between 2 approaches :
    • git rebase : this will try to place your local commits after the new head of remote branch (this avoids to create a merge commit)
    • git merge : this will merge your local branch and the remote-tracking branch.

If you want to rebase commits from the server, use git fetch then git rebase

Also remember that with Git there is an intermediate step between the workspace and local repository : the index.

Workflow

The following workflow applies to the developers with write access on Orfeo Toolbox Git repositories.

OTB workflow

What are the constraints in OTB project?

The guidelines used to create the workflow are:

  • Keep it simple
  • Test nightly the same code on all platforms
  • Share feature branches with all developers
  • Offer the possibility to test a developer's feature branch in a experimental section
  • Allow external contributions

What model should be used?

The initial approach was to re-use and adapt the gitflow to the constraints and development habits in OTB. So there are only 3 main branches:

  • develop : it can be considered as an integration branch, but the development guidelines assure that this branch remains healthy and ready to ship. This branch is extensively tested and integration of new features is done carefully.
What commits should go in this branch ? Mainly merge commits from feature branches go into develop. But others types of commits can go directly in develop : typos, documentation, compilation warning and error fixes, test fixing, small bug-fixes that affects only develop (and not the last stable release).
  • nightly : it is a read-only copy of the develop branch that is updated each night at 19h50 (CET/CEST) so that platforms can safely pull this branch at 20h00.
What commits should go in this branch ? NOTHING ! A bot is taking care of the nightly update, this branch is simply fast-forwarded to the develop head.
  • master : branch which contains the released code with the version tag, it can be considered a fairly stable branch. It contains the latest release.
What commits should go in this branch ? Only merges from the develop branch at the end of each release process. Note that only a subset of Git users can push to this branch.

The other branches are :

  • feature branches : where new features are developed. They should be forked from the develop branch, and named depending on the feature. In this branch you have more freedom than in develop branch, your code can be in a "work in progress" state. When developments on the feature are done (code, tests and documentation), you have to enable dashboard tests on this branch (see this paragraph). If the branch develop has moved during the development of the feature, you should synchronize your feature branch with develop : merge develop into your feature branch and sort out the conflicts. The feature branches can be merged into develop only when the release manager gives his approval. After the feature branch is merged AND pushed on the server, the branch has no particular reason exist anymore since following bug fixes will go in the develop branch. Thus, in order to keep a clear view of the branch list, it is advised to remove the merged feature branches (after checking your work is present in the develop branch !).
What commits should go in this branch ? All commits related to the development of this feature, synchronization merges from develop.
  • release-X.Y : these branches are forked from develop at each feature freeze.
What commits should go in this branch ? Merges from Hotfixes for this release. Tags can be added to this branch to identify patches versions (i.e. X.Y.1, X.Y.2, ...)
  • Tracked bugfix branch : when a bug is found on a given release X.Y, it should be tracked on Mantis. The fix for this bug should be made on a branch deriving from the corresponding release-X.Y branch. Then, this branch is merged into the release branch release-X.Y and optionally into develop if the issue also impacts develop. See this section for details.

The following main rules come along with the workflow described above :

  • Each new feature should start as a branch.
  • Each “large” feature branch should be shared publicly.
  • Only bug fixes should be done directly in develop.

When someone without write access on official repository wants to do an external contribution, this person may use the OTB github official mirror to use the pull request mechanism. So an OTB developer should fork this repository, add a branch with its contribution and do the pull request. After validation this pull request is integrated in a feature branch for testing. After checking that everything is ok and release manager approval, merge into develop or into release-X.Y branch for hotfix.

What is a bugfix?

The purpose of this section is to describe and illustrate what is a bugfix and what is not. Some general conditions can be listed to describe a bug fix :

  • the modifications solve an issue that is not a limitation of the implemented algorithm (crash, wrong results, incorrect information displayed, ...). There is a difference between bugfix and performance improvement.
  • the modifications preserve the functional perimeter : the purpose of a bugfix is not to add new features
  • the modifications don't involve a deep refactoring of the code.

Examples of commits that can be classified as bugfix :

  • fix a formula
  • check if pointer is null before using it
  • improve computation time by removing useless actions

Examples of commits that aren't bugfixes :

  • improve computation precision (float -> double)
  • new functionality
  • improve computation time by tuning the implemented algorithm
  • API change

How to push a bugfix (related to a Mantis entry)

  • Start from last stable release branch release-X.Y:
$ git checkout release-X.Y
  • Create a specific branch for the bugfix:
$ git checkout -b bugfix-nb
  • Apply and commit your fix:
$ git commit -a -m "BUG: fix bug Mantis-nb"
  • Merge this bugfix branch to the last stable release branch:
$ git checkout release-X.Y
$ git merge --no-ff bugfix-nb
  • Merge also this bugfix branch to the develop branch (if the bug also occurs on develop):
$ git checkout develop
$ git merge --no-ff bugfix-nb
  • Share the bugfix:
git push origin develop
git push origin release-X.Y
  • Delete the bugfix branch:
$ git branch -d bugfix-nb
  • Update mantis status

Which repositories are affected?

The source repositories that will follow this workflow are : OTB, Ice and Monteverdi.

All the other repositories have no particular workflow (not yet perhaps), they use a single master branch.

What Git commands should I know for this workflow?

Let's assume you have a clone of the OTB repository, the first thing you need to learn is to keep you repository on the develop branch and keep this branch up-to-date : 

$ git checkout develop
$ git fetch

When you want to update your local branch to get new commits from the server (origin/develop), prefer using the rebase strategy. It will put your local commits after the tip of origin/develop and you won't have to do a specific commit for the merge : 

$ git rebase

Note : be careful if you try to rebase a feature branch on the head of develop branch. If you do this, make sure you known what you're doing. If commits from your feature branch are already pushed on the server, bad things will happen.

When you create a new feature, make a dedicated branch and switch to it: 

$ git checkout -b my_feature

When you want to publish your branch on the server : 

$ git push origin my_feature

If you need to track new commits in this branch (commits from other developers), you should specify the remote tracking branch corresponding to your local 'my_feature' : 

git branch -u origin/my_feature  my_feature
When your feature is ready for testing, you can add it to the list of nightly tested feature branches : simply add the branch name in the file : 
OTB-DevUtils/Config/feature_branches.txt

When your feature is ready for integration : 

$ git checkout develop
$ git pull --rebase
$ git merge my_feature

Then you can clean the list of nightly tested feature branches.


If you have a Pull request on github.com/orfeotoolbox/OTB

The github project repository is a mirror of official OTB git repository. All commits happen in official git repository and is then copied to github repo. So If you happen to have a pull request via github. Please notify about your changes on otb-developers googlegroup. Once the changes are reviewed it can be merged into official otb repository using the below workflow. 

Name of repository OTB-Devutils
pull request number: 1
remote name: pull-<pull-request-number> = pull-1
url of pull request repository: https://github.com/kalxas/OTB-DevUtils
name of branch to merge: opensuse

EXPORT editor=nano

git clone https://rkanavath@git.orfeo-toolbox.org/git/otb-devutils.git devutils
cd devutils
git checkout master
git remote add pull-1 https://github.com/kalxas/OTB-DevUtils
git remote -v (optional)
git fetch pull-1
git branch (optional)
git merge --no-ff pull-1/opensuse
git push

For PR on OTB GitHub clone on develop branch: 


Merging via command line

Step 1: From your project repository, check out a new branch and test the changes.

git checkout -b dmci99-develop develop
git pull https://github.com/dmci99/OTB.git develop

Step 2: Merge the changes and update on otb official repository (git.orfeo-toolbox.org/git/otb). DON'T PUSH TO OTB GITHUB REPO WHICH IS A MIRROR OF THE OFFICIAL GIT REPO ON ORFEO-TOOLBOX.ORG.

git checkout develop
git merge --no-ff dmci99-develop
git push origin develop

Mercurial Repository migration

OTB Team has decided to move from Mercurial to Git after 5.0.0 release. The epic discussion happened in otb-developers on 10/2014!.

Technical aspects of this migration will be recorded in this wiki page.

Scrum activities will be done via OTB JIRA platform: OTB-731

Calendar

Oct/2014

  • Disucssion started

Jun/2015

  • OTB 5.0.0 released!

Jul/2015

  • Freezed commits onto mercurial repositories. (still there is read access)
  • Dashboard submission slowly starts using git.orfeo-toolbox.org
Retrieved from "https://wiki.orfeo-toolbox.org/index.php?title=Git&oldid=9927"