Difference between revisions of "ITK/Gerrit/Primer"

From KitwarePublic
< ITK‎ | Gerrit
Jump to navigationJump to search
(Replaced content with "This page previously contained information on use of Gerrit for ITK. The old information has been removed to avoid confusion. Please get started here instead.")
 
(37 intermediate revisions by 7 users not shown)
Line 1: Line 1:
This primer is to aid the ITK developer community in using Gerrit.  Some of the idiosyncrasies of Gerrit take a little work to understand and appreciate, especially if one is new to using the [http://git-scm.com/ git] distributed revision control system.
+
This page previously contained information on use of Gerrit for ITK.
 
+
The old information has been removed to avoid confusion.
==Gerrit basics==
+
Please [[ITK/Git|get started here]] instead.
Gerrit is designed to take a single change with a change log and make it publicly available for comments and revisions.  Once the change has been sufficiently reviewed and approved, it will be pushed into the official ITK repository.  Gerrit addresses the problem of many changes scattered about many git repositories by bringing them into a central place and allowing commenting and changes to become transparent to the rest of the community.
 
 
 
===Creating a Gerrit account===
 
In order to register you need to [http://openid.net/get-an-openid/ get an OpenID]. Be aware that a [http://www.gmail.com GMail] account automatically gives you an OpenID.
 
 
 
To register with Gerrit, first have your OpenID ready.  Then visit http://review.source.kitware.com/.  Click the "Register" link in the upper left.  If you have a Google or Yahoo account, click on the "Register with a Google account".  This will create your account.  Otherwise, enter the URL of an OpenID provider.
 
 
 
==git / Gerrit workflow==
 
For the sake of this primer, we'll be making a series of small documentation changes to ITK code.  The basic workflow from the developer's standpoint is:
 
 
 
* Clone the ITK official repository
 
* Create a topic branch
 
* Edit, commit, edit, commit, ad infinitum
 
* Compress your branch into a single commit
 
* Push your changes into Gerrit
 
* Review
 
* Stage changes into the ITK official repository
 
 
 
These steps will be detailed in the next sections.
 
 
 
==== Clone the ITK official repository ====
 
The instructions for cloning the official repository are [[ITK/Git|here]]. For the minimalist:
 
 
 
git clone git://itk.org/ITK.git
 
cd ITK
 
 
 
==== Create a topic branch ====
 
git works well to create "micro-branches".  Frequently, branches are considered poor practice in centralized revision control systems such as CVS and Subversion.  However, in git branches are typically very easy to work with and manipulate.  They are required for working with Gerrit, so get used to them.
 
 
 
We'll call our branch GerritPrimer.  The branch may be created it two steps:
 
 
 
git branch GerritPrimer    # Create a new branch from our existing revision
 
git checkout GerritPrimer  # Switch our working directory into the GerritPrimer branch
 
 
 
or you can do this all at once:
 
 
 
git checkout -b GerritPrimer  # Create GerritPrimer and switch the working directory into that revision
 
 
 
When we are finished, our revision history looks like this:
 
 
 
[[File:GerritPrimerBranch.png]]
 
 
 
Notice that GerritPrimer, master, origin/HEAD and origin/master branches all point to the same commit.  You can think of branches is movable labels that point to a particular commit in the revision history.  As we add code and commit our changes, we'll see GerritPrimer move.
 
 
 
==== Edit, commit, edit, commit, ad infinitum ====
 
Next, we'll edit some files and commit the changes.  In this primer, we'll make 3 changes.
 
 
 
Edit ITK/Code/BasicFilters/itkRecursiveGaussianImageFilter.h
 
add " * \see DiscreteGaussianImageFilter" on line 54
 
 
 
Next we ask git to show us what's happening:
 
 
 
<pre>
 
revelation:ITK(GerritPrimer) blezek$ git status
 
# On branch GerritPrimer
 
# Changed but not updated:
 
#  (use "git add <file>..." to update what will be committed)
 
#  (use "git checkout -- <file>..." to discard changes in working directory)
 
#
 
# modified:  Code/BasicFilters/itkRecursiveGaussianImageFilter.h
 
#
 
no changes added to commit (use "git add" and/or "git commit -a")
 
</pre>
 
 
 
git has the concept of an index, or an area where changes are stored before they are committed.  In the listing above, git knows that Code/BasicFilters/itkRecursiveGaussianImageFilter.h is changed, but it has not yet staged that change into the index.  To tell git that we want to add this change into the next commit, and make the commit we can do this in two steps:
 
 
 
git add Code/BasicFilters/itkRecursiveGaussianImageFilter.h  # Add the modified code into the index
 
git commit                                                    # commit all modifications
 
 
 
or in one step:
 
 
 
git commit -a    # Auto-add all modified files into the index, then commit all modifications
 
 
 
After two more commits, our repository looks like this:
 
 
 
[[File:GerritPrimerCommits.png‎]]
 
 
 
From where we made the branch (master, origin/HEAD, origin/master), we have three commits.  Notice that the GerritPrimer tag has moved along with our commits.
 
 
 
==== Compress your branch into a single commit ====
 
 
 
 
 
==== Push your changes into Gerrit ====
 
==== Review ====
 
==== Stage changes into the ITK official repository ====
 

Latest revision as of 12:30, 3 June 2011

This page previously contained information on use of Gerrit for ITK. The old information has been removed to avoid confusion. Please get started here instead.