Home

Getting started

The goal of this tutorial is to review the source code of the QGears Review tool itself, presenting common usage scenarios and a recommended review workflow.

Note that this document assumes a basic knowledge of Eclipse, SVN and Subversive from the reader.

Preparing the demo environment

After reading README.md on what QGears Review Tool is, and having the installation successfully accomplished with the help of INSTALL.md, additional handcrafted configuration is necessary to use the tool. As the QGears Review Tool supports reviewing files only in SVN repositories, the SVN interface of GitHub will be used. During the tutorial, keep a command line terminal ready at hand, and use the same session all the way up the line.

The content of the qgears-review-tool github repo repository will be replicated into local SVN repo in the example. Your commits will land in there, without requiring to set up an SVN server just for the example.

First, check out the revision 10 of the QGears Review Tool repo into a temporary location:

svn co https://github.com/qgears/qgears-review-tool/trunk@10 /tmp/qgears-review-tool-trunk-r10

Create a local SVN repository and import the source tree:

cd ~
mkdir -p temp/qgears-svn-replica
cd temp/qgears-svn-replica
svnadmin create qgears-review-tool
svn import /tmp/qgears-review-tool-trunk-r10 file:///home/user1/temp/qgears-svn-replica/qgears-review-tool/trunk -m "Initial import of QGears Review Tool for reviewing its source code"

Check out the whole trunk of the qgears-review-tool SVN repo into an arbitrary directory! This directory will further be referred to as $SRCDIR. Commands to execute:

cd
export SRCDIR=$HOME/qreviewtool-svn
mkdir $SRCDIR
svn co file://$HOME/temp/qgears-svn-replica/qgears-review-tool/trunk ```$SRCDIR```

Project-specific configuration

The project-specific configuration is shared between all the reviewers, and serves the following purposes:

• identifies the SCM working copy root(s) into which source code is checked out
• identifies files which are subject to review

Create a folder for the reviews and review configurations in $SRCDIR, let's call it 'review':

export REVIEWDIR=$SRCDIR/review
mkdir -p $REVIEWDIR

Create a folder for storing the configuration files and review data:

export REVIEW_PRJ_CFG_DIR=$REVIEWDIR/config-qreviewtool
mkdir -p $REVIEW_PRJ_CFG_DIR

The following further configuration must be provided:

• one (or more) directories, in which, reviewed files are to be searched recursively:

echo "svn qreviewsvn_workingcopy
" > $REVIEW_PRJ_CFG_DIR/sourcefolders

• the entry beginning with svn $projectname refers to a map.$projectname=$SRCDIR entry in your sourcefoldermappings.properties file (see below), determining into which directory exactly the reviewed project is checked out on your workstation

• one or more of these entries may be specified, allowing complex projects to be reviewed from multiple SCM repositories

• patterns for filtering the source code files:

echo "**/*.java
" > $REVIEW_PRJ_CFG_DIR/sourcefilepatterns

• a filter for specifying set of files which are subject to review:

export SAMPLE_FILESET_DIR=$REVIEW_PRJ_CFG_DIR/filesets/set1
mkdir -p $SAMPLE_FILESET_DIR
echo "whitelistfileset

#
# File set definition that contains all
# classes that needed to be reviewed.
# Source files must be specified by 
# valid Java regular expressions.
#

# Critical codes used by both the web 
# and Eclipse user interfaces, except 
# the code of the web interface itself
.*/hu.qgears.review/.*(^web).*java

# Controller code of most commonly used 
# functionality
.*/CreateReviewEntryAction.java
.*/CompareWithHeadAction.java

" > $SAMPLE_FILESET_DIR/filesetdefinition

User-specific configuration

Create a subfolder in $REVIEWDIR, called settings-$USER, which will store (only) your main, user-specific configuration file:

export USER_SETTINGS_DIR=$REVIEWDIR/settings-$USER
mkdir -p $USER_SETTINGS_DIR

Create your personal, main configuration file called sourcefoldermappings.properties in the $USER_SETTINGS_DIR directory - for the sake of simplicity, copy-paste and execute the command below:

echo "# QGears Review tool user-specific config file
config=$REVIEW_PRJ_CFG_DIR
map.qreviewsvn_workingcopy=$SRCDIR
" > $USER_SETTINGS_DIR/sourcefoldermappings.properties

Explanation of the config file entries:

• map.qreviewsvn_workingcopy: the root directory of an SVN working copy of the reviewed software project - note that more than one map* entry may be present in a sourcefoldermappings.properties file, as the reviewed files may be contained in more than one SCM repositories
• config: absolute path of a subdirectory with settings and saved code reviews specific to reviewing a software project - more detailed information in the next chapter

Assembling the Eclipse workspace

For the rest of the tutorial, use an Eclipse installation, into which the QGears Review Tool is preinstalled according to the INSTALL.md file found in the qgears-review-tool github repo.

In this Eclipse, create a workspace, into which the projects from $SRCDIR are all imported.

Now you have a workspace with 5 projects imported, all at revision 1:

• hu.qgears.review
• hu.qgears.review.build
• hu.qgears.review.eclipse.ui
• hu.qgears.review.feature
• hu.qgears.sonar.client

In order to follow the changes of the review itself, it is strongly advised to import the $REVIEWDIR into the workspace, as a generic project and commit it into the SVN.

Specify your personal configuration file (sourcefoldermappings.properties) via Window menu > Preferences > Review tool preferences > Configuration file path > Browse

For convenience, a perspective is defined to aid the review process. The name of this perspective is Q-gears review tool. Assumption of the following parts of the tutorial is having this perspective open.