Private development on gforge

Steps to follow are :

To do only the first time

  • configure git
  • create your private area on gforge
  • fork official project you want to work on

For each new modification

  • create a new //branch// with explicit name (ex: //fix_app_crash_mac_os_10_9//)
  • work on your new branch
  • prepare your work for merging
  • submit your pull request

Note

If you are a new git user, you can try git on try.github.io to be more familiar with git commands. You can also have a look to Atlassian Git documentation.

Configure git

"--global" refer to your username on your computer. So you need to config only once for you.

If you want a specific config for a specific project, please use "--local"

git config --global user.name "my name"
git config --global user.email myemail@foo.com
git config --global push.default simple
git config --global core.editor <your_favorite_editor>

Create your private area

Do this step only one time, once created, never do it again.

To create a private area on gforge, you need a @inria.fr email address. Be sure this address is used, else, you can change your gforge email address.

Please respect naming convention below

  1. Register a new project :
  • Full name: private git Firstname Familyname
  • Description: private repositories (you can write what you want here)
  • Unix name: usernamegit (username is your gforge account login, just add git at the end)
  • Source code: select git button
  • Start from empty project

Create your fork

The official project you want to fork in order to contribute will be called "upstream". To be able to contribute to this "upstream" project, you need to "fork it" (make a private clone of it). To fork it, do these steps (do it only one time for a project)

  1. Go to My page
  2. click on your private repositories project
  3. click on administration tab
  4. click on tools tab
  5. enable source code management (SCM) by checking it, then update
  6. click on SCM/Code source
  7. click on administration tab
  8. click on "SCM/Code source"
  • repository name: same as repository you want to fork (ex: oalab-tissue)
  • description: fork full-address-to-forked repository (ex: fork git+ssh://username@scm.gforge.inria.fr//gitroot/project/oalab-tissue.git)
  • Initial clone URL: erase name, field must be empty

Wait at least one hour!

  1. Click on "SCM/Source code"
  2. Copy git command (something like git clone git+ssh://username@scm.gforge.inria.fr//gitroot/usernamegit/usernamegit.git)
  3. Paste this command in a terminal to clone project on your disk

Configure your fork

git remote add upstream giturl
# with giturl something like git+ssh://username@scm.gforge.inria.fr//gitroot/project/repository.git
# for example: git+ssh://username@scm.gforge.inria.fr//gitroot/oalab/oalab-tissue.git
git fetch upstream

Your fork is now ready to work on !

Create development branch

You must create a branch for each new feature, bug fix, and so on. Development must be short : one branch = one task

NEVER NEVER work on master, always on a branch

Get last version of upstream/master

git checkout master # go to your local master branch
git pull upstream master # update it with upstream master
git push # push upstream changes to your personal repository

Now, you can create your new branch. Please choose an explicit name.

git checkout -b wip_fix_app_crash_mac_os_10_9
git push --set-upstream origin wip_fix_app_crash_mac_os_10_9
# wip means "work in progress"

Work on your modifications

# edit file(s)
git commit
git add mynewfile.py
git commit
# edit file(s)
git commit

Commit message

Please write a good commit message:

Try to limit using the -m commit flag.

If using the simpler git commit command it should open up Vim (if it’s your default editor) where you can construct a better commit by following some of these simple steps.

  • The first line should be a short summary. Referencing the bug number or the main accomplishment of the change. e.g “Fixes issue #8976″. This is the title of your commit and should be less than 50 characters.
  • Then a line break.
  • Followed by a longer detailed description about the things that changed. This section is a really good place to explain what and why. You could cover statistics, performance wins, roadblocks, etc. The text should be wrapped at 72 characters.

Save your branch and commits on your personal repository.

git push origin wip_fix_app_crash_mac_os_10_9

Prepare your work for merging

Before asking other to integrate your work, you must clean it. First get last modifications and work on a new branch created especially for cleaning.

Get last version of upstream/master

git checkout master # go to your local master branch
git pull upstream master # update it with upstream master
git push # push upstream changes to your personal repository

It is safer to create a new branch for rebase

git checkout wip_fix_app_crash_mac_os_10_9 # get your development branch
git checkout -b fix_app_crash_mac_os_10_9 # create and checkout new branch, now we removed the "wip"
git rebase master

If master has diverged during your work, conflicts can occur ! Fix conflicts for each file and finish rebase :

# edit file1 and solve conflicts
git add file1 # say to git that conflict is resolved
# edit file2 and solve conflicts
git add file2
git rebase --continue

If rebase has gone wrong, for example you've rebased the wrong branch, you can cancel it with

git rebase --abort

Note

For advanced user, you can also use git rebase --interactive.

Submit your pull-request

Go to upstream project page on gforge.inria.fr and click on tracker tab (outils suivi). Click on "pull-request-project" link, and then create a new entry, and do not forget to give an url. This url is used by reviewers to reach your work, review it and integrate it.

url is something like: git+ssh://username@scm.gforge.inria.fr//gitroot/username/project.git You can obtain it with,

git remote -v

origin   git+ssh://username@scm.gforge.inria.fr//gitroot/usernamegit/project.git (fetch)
origin   git+ssh://username@scm.gforge.inria.fr//gitroot/usernamegit/project.git (push)
upstream git+ssh://username@scm.gforge.inria.fr//gitroot/organization/project.git (fetch)
upstream git+ssh://username@scm.gforge.inria.fr//gitroot/organization/project.git (push)

Copy paste line corresponding to origin and remove "git+ssh://username@"

branch is the name of your branch, for example "fix_app_crash_mac_os_10_9".

You need to allow at list one official "integrator" to read your private repository. For that, on your private project, go to "user and permissions", add a new "reviewer" (or integrator) role with "read access" to repository and then add the integrator.

Reviewer: review branch

Read this part only if you are a reviewer !

git remote add username git+ssh://username@scm.gforge.inria.fr//gitroot/username/project.git
git fetch username
git checkout username/branch -b review_username_branch
# review changes, if all correct, write it on tracker and set state to "confirmed"

Integrator: integrate branch

Read this paragraph only if you are an integrator !

# Check branch has not changed since previous review
git checkout review_username_branch
git pull

git checkout master
git pull upstream master

# --no-ff (no fast forward) is used to create a merge commit.
# This commit is used to create a link between tracker and git repository
git merge --no-ff review_username_branch

It is very important to follow this message convention:

Merge pr/[#trackerid] from branch username/branchname into master
#example: Merge pr/[#18786] from branch gbaty/support_repr_vtk into master

Then push it to official repository

git push upstream master

Finally, set PR tracker state to "closed" and add comment "merged". This is important to signal to others contributors that pr has been integrated.

Finalization

If pull request has been integrated:

git checkout master
git pull upstream master

# Check you find all yours commits on upstream_master
# If yes:
# git branch --delete branch # delete branch locally
# git push origin :branch # delete branch on gforge fork

You can now start a new contribution cycle, see "Create development branch"