Git Usage and Migration in GateIn Portal

Status

Initial planning. Scheduling migration plan and defining usage in the project

Owner

Boleslaw Dawidowicz and Julien Viet

Introduction

Git has few strenghts over SVN.

• Fast
• Distributed/offline
• Stashes
• Real branches and tags (not just lame copies!)
• Fast, reliable, effective merging

In case of GateIn portal project two reasons are currently major ones:

• Speed. SVN becomes very slow with growing size of the whole repository which affects overall work efficiency
• Distributed working environment and branches. Currently more and more work in the project happens in separate branches. When this work is around bigger features it leads to big bloated commits as with SVN it is not possible to preserve commit history in such scenarios.

Additionally it will also help for different kind of scenarios where:

• productization of GateIn is easier to do
• customer patch can be kept in privacy
• other teams (UI, test) can contribute without requiring a dedicated access

Solution

GateIn Portal project will be migrated to github. Migration of each project component will be scheduled and the way team cooperates around the source code will be adapted to reuse concepts from git flow.

Specification

There are two parts of this specification

1. Migration - with concrete schedule, split of responsibility and specific requirements
2. Git usage - which will led to creation of separate document specifying usage of git in the project.

Migration

There won’t be any one time migration effort. GateIn Portal project will first start using git repository for any new component that we introduce. Main requirement for migrating any GateIn code that currently lives in SVN is to preserve commit history. For specific components it may be decided to not migrate all tags and branches fully and rely on read only access to the history in svn.

Server

GateIn Portal will leverage GitHub infrastructure. Organization URL: github.com/gatein

Schedule

[Table with schedule; Columns - Component; SVN URL; Date; GitHub URL; Person in charge; Comments / Status]

Git Usage

History rewrite

Unlike SVN, GIT allows history rewrite (push --force) and it is important to specify its usage as it is a double edges sword, it has advantages and drawbacks:

• History can be rewritten to merge similar commits in a single one
• Comments can be changed (for instance to add a missing JIRA)
• Remove things that were pushed by mistake (and it will happen)
• History can be lost with a wrong manipulation
• A rewrite will require more work for other repositories that created a branch from rewritten commit

Therefore history rewrite usage must be precisely defined

• Rewrite should not be done frequently but should be discussed before
• Rewrite must be motivated
• Rewrite must not be done in the history preceding a public tag

GIT and JIRA

GIT provides several kind of merge possiblities (in a broad sense)

• Merge: takes several commits and unify them
• Rebase: replays commit of a branch on the HEAD of another branch

The picture shows what happens with one future and two futures (two futures happens when concurrent modification of the branch is done).

Branches (several commits) and JIRA

Most of the time we want to identify a JIRA and a feature. In case of GIT, the feature can be made by one or several commits. We will care here about the case where several commits are related to a single JIRA. In order to identify this feature we can consider that those commits are done in a branch and leverage the “merge” commit to add the JIRA in the comment, we have two cases:

• The history has been divided into two futures and in that case the merge commit always exist
• The history has one future (no fork) and in that case by default GIT performs a fast forward merge. In that case we cannot really identify the feature commits as everything is linear and  we don’t have explicit boundaries of

• The first commit of the feature
• The last commit of the feature

Further more the merge commit does not exist and it cannot be labelled with the JIRA (unless we put the same JIRA on each commit of the branch, which is a solution that is error prone). For that matter we should instead make non fast forward merge always in order to distinguish the work done related to the JIRA.

Example

>echo ‘foo’ > main.txt

>git add main.txt

>git commit -m ‘added main.txt’

>git checkout -b bar_feature

>echo ‘bar’ > main.txt

>git add main.txt

>git commit -m ‘changed bar’

>echo ‘bar2’ > main.txt

>git add main.txt

>git commit -m ‘updated bar’

>git checkout master

>git merge --no-ff -m ‘GTNPORTAL-1234’

Commit and JIRA

On the other hand when a single commit resolves a JIRA, it makes more sense to not have a branch. Which can be achieved by a cherry-pick or rebase of that commit onto the HEAD of the branch.

In that case we want to avoid merge and instead keep a linear history as only one single commit is related to the JIRA.

Workflows

Workflow are an important part of git and play an essential role.

Tools at GitHub

Tracker

GitHub provides its own set of tools like tracker. GateIn project will still rely on JIRA and aims to reuse as much as it is possible from jboss.org infrastructure. Therefore using tracker or other tools from github i in combination with gatein components is forbidden.

Pull request

Study pull request mechanism. At least automatic merge of pull request done by GitHub should not be used and instead it should be done manually. I will describe later the difference between a pull request merge and a pull request rebase.

Usage

TBD