Home | Download/Install | Documentation | Packages | Screenshots | News | Forum/Mailing-lists | Contact | GForge

GitHub and GForge

Context

Today, source code is hosted on GForge and use the Source Code Management (SCM) subversion. A part is public (OpenAlea) and a part is private (VPlants, Alinea). In this private part, a subpart is disseminated at each release, once or twice a year.

Subversion (SVN) is a centralized SCM : all developments are done on an unique central repository. Users work on a local copy but a network connection is required for numerous commands.

Problems

If somebody wants to participate to the code (bug fix, new feature…) which is on the private repository, he had to register himself on this repo. Everybody can't be registered.

We want to facilitate external development process.

GitHub provide a set of social tools which permit to ease external development. But, we can't only move our sources from GForge to GitHub because GitHub private repositories are not free.

We want :

  • to permit to regular developers to work on a private repo if they want
  • to permit to occasional developers to participate easily to public development
  • take advantage of github features and visibility

SVN nowaday, also shows limits in development workflow. It is well designed for a company/institue-centered development with classical workflow (for example a V-Model one) but is not so convenient for agile programming. For example, it is hard to explore two different developments at the same time or work on experimental approaches because branching system (and merging) is not easy. Occasional external contributors can be discouraged to work directly on the official repository, due to the fear of doing mistake and break project.

Different kind of developments have been identified. Workflow to follow depends on that.

  1. External contributor / Public development
    • uses code as 3rd-party software/library
    • public development
    • fixes bugs, adds features
  2. Developper on a private project
    • create a project or join one
    • private development
    • shares with coworkers/collaborators
  3. Developper on an existing public project, doing private developments
    • private development
    • shares with coworkers/collaborators
    • stays synchronised and contribute to public repository, stays synchronised without contributing to public repository or never synchronise
  4. Release Manager
    • merge, review, test
    • create a consistent release and tag it
    • can be private or public

Special cases :

  1. create a project
  2. join a project
  3. publish a project

Proposed solution

Private development can stay on private GForge repository (gforge/vp/Proj). Public development can be done on public GitHub repository (github/vp/Proj). Public development (on GitHub) but with a temporarily private part can be forked and temporarily done on private repository (GForge).

All possible workflows are described on next figure :

Workflow

See sameworkflow in french

Organizations

For this, we propose:

  • to use a GitHub organization named openalea
  • to use a GitHub organization named VirtualPlants to manage development of VirtualPlants team
  • to use other organizations for others teams if necessary
  • openalea organization contain all openalea modules OR link to external modules (see git submodule). So we can create ”meta modules” and download OpenAlea with only one command even if repositories are in other organizations. And modules are still independents.

Repositories

We want to download OpenAlea with only one command. But, we want to have some independents repos (to have different owners, to let some modules independent of others…).

Detailed workflows

Public development on github

If you are an external contributor and you want to make a public development on existing github project

See Public development on github.

Developper on a private project

Workflow is exactly the current svn workflow but with git.

You have to:

  1. Create a repository for each independent project (you can't create private project on GitHub for free, so if you can, use GForge).
  2. Work on it.
  3. That's all…

Developper on an existing public project, doing private developments

If you arrive on an existing public project BUT you want to make private development.

Duplicate repo from public to private

If private repo exists, work on it like if it was a totally private repo. Else you have to create it:

  1. go on public repo (github/vp/Proj)
  2. fork it (github/user/Proj)
  3. create a new branch with explicit name (ex: fix_print_branch)
  4. relocate this branch on private repo (gforge/vp/Proj)
  5. work on your private branch
Publish a private repo on public one or update public repo
  • todo

Git User Guide

Git & Github features

submodules

A submodule is a link to another git repository at a given snapshot (commit). By default, submodules are not cloned but you can do it easily with 2 commands.

Important information :

  • a submodule do not track the branch. If branch changes (new commit on master for example), submodule stays to initial snapshot. Tha means you must track new changes manually. Advantage: ensure a coherence. Drawback: no automatic synchronization.
  • before git 1.8.5, managing submodules is not convenient. Now, it as easy as managing simple files
  • GitHub displays very well submodules. You can reach original repository and corresponding snapshot easily

Git commands clearly distinguish parent module and submodules so be careful :

  • git commands at root level works for parent repository only and give no information about submodules
  • git commands in a submodule directory give no information about “parent” repository

Git OpenAlea tuto

Git external tutos

Git main commands

  • git clone
  • git pull
  • git add
  • git commit
  • git push
  • git rebase
  • git branch
  • git help

Git vs SVN "equivalences"

SVN Git
checkout clone
update pull
commit push

Free Git Graphical Clients

GitHub only for GitHub (not compatible with GForge for example): GitHub for Windows, GitHub for Mac, GitHub for Eclipse

Tortoise Git for Windows

git-cola cross-platform

GitEye cross-platform

GitX-dev for Mac

And many others…

Git advice

Some advice from Fernando Perez

  • one task = one branch
  • name your branches sensibly (ex: fix_print_bug_branch)
  • Never merge back from trunk into your feature branch
  • If you absolutely need to merge something from trunk (because it has fixes you need for your own work), then rebase on top of trunk before making your pull request, so that your branch applies cleanly on top of trunk as a self-contained unit without criss-crossing.
  • For reviewers: edit the merge message before you push, by adding a short explanation of what the branch did, along with a final 'Closes gh-XXX.' string, so the pull request is auto-closed and the ticket and closing commit get automatically linked.

See Also

 
documentation/core/propositions/107_git.txt · Last modified: 2014/02/13 14:24 by user   Back to top
INRIA   INRA     CIRAD     AGROPOLIS IBC
INRIA GForge RSS feed Valid XHTML 1.0 Valid CSS Driven by DokuWiki