2.2. Configuration

2.2.1. Codestriker Database

The $db variable should be set to a DBI URL representing the Codestriker database that was created, as specified in Section 2.1. Basically, if you are using PostgreSQL, this should be:

$db = 'DBI:Pg:dbname=codestrikerdb';

$db = 'DBI:mysql:dbname=codestrikerdb';

$db = 'DBI:mysql:dbname=codestrikerdb;host=dbhost';

# Database user.
$dbuser = 'codestriker';

# Database password.
$dbpasswd = 'cspasswd';

2.2.2. Email

When a code review topic is created, or a comment against a review is made, an email is sent out as a notification mechanism. Codestriker needs to know what mail host it can use for sending email messages. The configuration file default is "localhost":

# Location of the mailing host.  This is used when sending out codestriker
# comments.
$mailhost = 'localhost';
           

# Set the user and password parameters if $mailhost requires SMTP
# authentication.  If commented out, it is assumed authentication is 
# not required.
$mailuser = 'smtpuser';
$mailpasswd = 'smtppasswd';
           

2.2.3. Compression

Some of the HTML pages generated by Codestriker can be quite large, depending on the review size. If your deployment is operating to users outside an intranet, it may be worth enabling this option to enable compression. Note, IE doesn't support receiving compressed HTML, so setting this option will have no effect. Initially, it is best to leave this option turned off (the default), and only to enable it if there is a significant performance problem.

# Indicate whether to try and compress output if the client browser
# supports it.  This can make a tremendous difference in bandwidth,
# especially over slow links.
$use_compression = 0;
	  

2.2.4. Source Code Management Systems

This part of the configuration deals with informing Codestriker what source code control systems you use. By doing this, Codestriker can then display reviews with revision information, and then allow the reviewer to view the entire contents of a file before a change, and with a change applied. When a review is created, the user specifies which source control system it is applied against (there may not be any, if it is just a simple patch or text file). For many Codestriker deployments, there may only be a single SCM system. There is currently support for CVS, Subversion, Perforce, Visual Source Safe, and ClearCase. Here are examples from the codestriker.conf file:

# Valid repositories which may be selected at the create topic screen.
# The order shown here is the order presented in the option list.  Most
# deployments will only require a single repository to be specified.
# Comment out / modify entries appropriate for your deployment.
#
# If this list is empty it won't be possible to view the entire contents of a
# file before the proposed change and/or after. All of the places 
# in the application that ask for, or display repository information will
# be hidden and lastly, it will be impossible to make a diff review topic
# on files that already checked in.
#
# You also need to make sure that the user running your webserver has
# permission to run the client SCM program (eg, cvs, p4, svn), and to
# connect to the repository.
@valid_repositories =
    (
     # Example CVSROOT of a CVS repository on the same machine as the
     # codestriker server.
     '/home/sits/cvs',

     # Example of a CVS repository which contains the URL to a viewcvs
     # installation (CVS web is also supported), followed by the
     # CVSROOT of the repository.
     'http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi /cvsroot',

     # The next example is the syntax used for specifying a Subversion
     # repository, which is simply the subversion repository URL
     # prefixed # by svn:
     'svn:http://svn.collab.net/repos/svn/trunk',

     # Subversion server with authentication.  The user name and
     # password should be added to the end and separated by
     # semicolons.
     'svn:http://svn.collab.net/repos/svn/trunk;username;password',

     # Subversion server that uses the Subversion protocol.
     'svn://my.subversion.server/repos/product/trunk',

     # Example CVS pserver config with username and password
     # specified.
     ':pserver:sits:password@cvs.sourceforge.net:/cvsroot',

     # Example CVS pserver config with proxy options.
     ':pserver;proxy=abc.com;proxyport=8080:sits:pwd@cvs.dev.net',

     # Example CVS pserver with empty password.
     ':pserver:anonymous:@cvs.sourceforge.net:/cvsroot',

     # Example CVS server which will be connected to with SSH.  This
     # assumes the appropriate ssh keys have been created so that the
     # process running the Codestriker application can connect to the
     # CVS server without requiring a password to be entered.
     ':ext:sits@localhost:/home/sits/cvs',

     # Visual SourceSafe repository on same machine at default
     # location.  Username "admin", password "password".
     'vss:admin;password',

     # Visual SourceSafe repository on same machine, but with specific
     # repository location specified.
     'vss:c:\\Program Files\\Microsoft Visual Studio\\VSS;admin;password',

     # Visual SourceSafe repository located on a network fileshare.
     'vss:\\\\VisualSourceSafeMachineName\\SharedRepositoryPath;admin;password',
     # Example Win32 CVS repository on the same machine.
     ':local:c:\\cvsrep',

     # Another Win32 CVS repository on the same machine.
     'c:/cvsrep2',

     # The next example is for a Perforce repository.  After the
     # leading :perforce identifier, the next two components are the
     # Perforce user and password parameters.  The last two parameters
     # after the '@' symbol represent the host and port number of
     # the Perforce server.
     'perforce:sits:password@localhost:1666',

     # The next example is a ClearCase repository, where the path is
     # the location of a shared snapshot view.  From this view, it
     # should be  possible to a file of any version can be 
     # retrieved from the vob using the "cleartool get" command.  It
     # is important that this snapshot view is accessible with the
     # same path specification for all developers.  This is because
     # a diff file created by a developer will refer to the snapshot
     # view, and will allow Codestriker to retrieve specific files
     # and versions mentioned in the review text, when necessary.
     # It is also important that the user account running the
     # webserver process has permission to access to the snapshot
     # view.
     'clearcase:c:\\stuff\\view_name\\vob_name',

     # The next example is a repository based off a ClearCase dynamic view.
     # The clearcase identifier is followed by the dyn indicator,
     # followed by the view name, followed by the location where the
     # view is loaded.
     # 'clearcase:dyn:viewname:/vobs'
    );
        

As explained by the comment in the codestriker.conf file, sometimes there is a benefit for displaying a name instead of a repository URL in the Codestriker UI.

# A mapping of repository URLs to names.  In any screen where a
# repository is displayed, if there is a mapping for the repository
# defined here, then the symbolic name will be displayed instead of
# its raw URL.  This is useful when the URL contains sensitive
# username/password information, or the symbolic name is more
# meaningful to the end-user.  If there is no mapping defined for a
# specific repository, its URL will be displayed.
$repository_name_map =
{
    '/home/sits/cvs' => 'Local CVS',
    ':pserver:sits:password@cvs.sourceforge.net:/cvsroot' => 'SF CVS'
};

	

During a review, it is sometimes beneficial to see the revision history of a file, such as information provided by CVSweb or ViewCVS. You can specify a mapping of repository names to URLs for this purpose, for example:

$file_viewer =
{
    '/home/sits/cvs' => 'http://localhost/cgi-bin/cvsweb.cgi'
};
	  

If you are using CVS, make sure the $cvs setting is set to the correct path. For UNIX, this is likely to be something like:

# Location of the cvs binary.
$cvs = '/usr/bin/cvs';
	  

# Location of the cvs binary.
$cvs = 'c:/gnu/bin/cvs';
	  

If you are using Subversion, make sure the $svn setting is set to the correct path.

If you are using Perforce, make sure the $p4 setting is set to the correct path.

If you are using Visual SourceSafe, make sure the $vss setting is set to the correct path.

2.2.5. Bug-Tracking Integration

It is often useful to link the creation of code review topics with the associated bug records that the code is fixing. That way, it is possible to read a bug record, and apart from reading the textual description as to how it has been resolved, Codestriker can add in a link to the code review topic, which shows the actual code which fixed the bug (and any important decisions made in the Codestriker comments). Currently, there is support for Bugzilla, Flyspray and TestDirector, but it is not difficult to add in support for other systems.

If you don't use a bugtracker you can skip this section, as by default, there is no linking to a bug tracking system. An example configuration could be as follows:

# Bug tracking type.
$bug_db = 'bugzilla';

# Bug database connection details.
$bug_db_host = 'localhost';
$bug_db_name = 'bugs';
$bug_db_password = 'bugs_password';
$bug_db_dbname = 'bugs';

# Bugzilla codestriker user id.
$bug_db_user_id = '2';
	  

The $bug_db_host setting indicates the hostname that holds the bugzilla database, while $bug_db_name and $bug_db_password contain the database username and password to connect to the Bugzilla database. The $bug_db_dbname setting contains the Bugzilla database name, which by default is "bugs". You can verify these settings by using mysql to connect to the Bugzilla database interactively.

Codestriker adds "comments" to the appropriate bug record whenever a code review topic has been created against it, or the review's state has changed. To do this, a special Bugzilla user needs to be created which the comments will be created against. Create the user using the Bugzilla interface, and call it "codestriker@yourhost.yourdomain". Then connect to the Bugzilla database using mysql, and execute the following command to determine the userid of the user just created:

SELECT userid FROM profiles WHERE
login_name = 'codestriker@yourhost.yourdomain';
	  

# Bugzilla codestriker user id.
$bug_db_user_id = '2';
	  

2.2.6. LXR Integration

Codestriker has been integrated with LXR, so that when performing a review, those identifiers known to LXR will be automatically hyperlinked. This is an enormous aid to the code reviewing process, as you can quickly determine where a variable/function/method/class is defined and where it is used quickly, while studying the proposed changes.

The LXR home page is located at http://lxr.sourceforge.net. The integration has been tested with LXR version 0.9.2.

Its possible that each source code repository is associated with a different LXR deployment. The default configuration file shows an example:

$lxr_map = 
{
    '/home/sits/cvs' => { db => 'DBI:Pg:dbname=lxr',
			  user => 'lxr',
			  password => '',
			  url => 'http://localhost.localdomain/lxr/ident?i='
			},

     'svn:http://svn.collab.net/repos/svn/trunk' =>
                        { db => 'DBI:Pg:dbname=lxr2',
			  user => 'lxr',
			  password => '',
			  url => 'http://localhost.localdomain/lxr2/ident?i='
			}
			  
};
	  

Each key is mapped to an object containing four attributes. The db attribute is a DBI URL of the LXR database, user is the database username, password is the database password, and url is the URL of the LXR deployment for the identifier search page.

If you don't have LXR installed, you can simply set this variable as follows:

$lxr_map = 
{
};
	  

Also note, LXR at present doesn't seem to work with Taint checking. To avoid warning messages, you'll need to comment out the "PerlTaintCheck On" line in your Apache httpd.conf file, and remove the -T switch at the top of the bin/codestriker.pl.base file.

2.2.7. Topic Text Encoding

Codestriker stores the topic text, description and comments as UTF-8. When creating a topic, Codestriker needs to be told what encoding your files are stored in. By default, Codestriker assumes it is UTF-8 (compatible with ASCII). If your source code files are stored in another encoding (for example, gb2312 for a Chinese team), this needs to be specified in the $topic_text_encoding variable.

# Character encoding to use when reading topic text.  Default is utf8
# (compatible with ASCII) if not set, but this can be over-ridden here.
# List of example encoding names can be retrieved from the following
# URL: http://perldoc.perl.org/Encode/Supported.html.
#$topic_text_encoding = 'utf8';
#$topic_text_encoding = 'gb2312';
	  

2.2.8. Deployment Options

There are a number of other options which affect how Codestriker runs. The most important ones are shown below. Unless you have specific reasons to, most intranet deployments of Codestriker can leave these options as is.

# Exclude these file types from review topics.   
# You will generally want to exclude any non-human-readable files.
@exclude_file_types = ('rtf', 'doc', 'gif', 'bmp', 'jpeg', 'jpg', 'mdb',
		       'ppt', 'vsd', 'xls', 'zip', 'tgz', 'tar', 'gz',
		       'opt', 'aps', 'ncb', 'a', 'so', 'dll', 'lib',
		       'exe', 'png', 'pdf', 'bin', 'out', 'ld', 'fm',
		       'indd', 'wav', 'o', 'obj', 'mpp', 'vsw', 'jfif',
		       'tif', 'tiff', 'xbm', 'fnt', 'ttf', 'pfm', 'pfb',
		       'eps', 'wpj', 'sxi');

# Indicate if topics can be listed/searched.  Turning this to false can be
# useful for "anonymous" installations of Codestriker.
$allow_searchlist = 1;

# Indicate if the repository attribute can be set to a topic.  If this
# is disabled, it won't be possible to view the entire contents of a
# file before the proposed change and/or after.  On some servers (such
# as sourceforge), the firewall doesn't allow CGI scripts to make
# remote connections.
$allow_repositories = 1;

# The following controls project configuration.  Each Codestriker topic is
# a member of a specific project.  Uncomment the option you want
# below.  Note the textual state names below cannot be changed.

# Default option, projects are enabled, but they have no state
# changing operations (ie, projects are always in state 'Open').
@project_states = ('Open');

# Don't use projects at all.  Effectively, an implicit "default
# project" is created and associated with all topics behind the scenes.
# @project_states = ();
#
# Allow for projects to be closed.  Closing a project will
# not allow new topics to be created in that project.
# @project_states = ('Open', 'Closed');
#
# Allow for projects to be deleted.  This is potentially a dangerous
# option to allow, as deleting a project will delete all of its member
# topics as well.  Use with caution.
# @project_states = ('Open', 'Deleted');
#
# Allow for projects to be closed and deleted.  Use with caution.
# @project_states = ('Open', 'Closed', 'Deleted');

# If true, don't display any email addresses in their true form, but
# truncate them, to beat SPAM harvesters.
$antispam_email = 0;
	  

2.2.9. Topic Length Restrictions

As explained by the comments in the configuration file, it is possible to limit the size of code review topics that will be accepted by the system:

# The number of problems found per line drops if the size of the 
# topic is too large. A common inspection pitfall is for authors to 
# attempt to review too much material and then miss problems. 
# These two options allow the Codestriker administrator to limit 
# the length of the topics. Topics that have more lines than 
# $maximum_topic_size_lines are rejected when they are created. 
# Topics that are larger than $suggested_topic_size_lines generate 
# a warning displayed in the topic page, but are accepted into the 
# system. Codestriker measures that length of the topic by counting 
# the number of lines in the topic text.
#
# The Codestriker default of not enforcing any limits is specified by
# settings either option to an empty string. If you are not sure 
# what a reasonable limit would be, start with a suggested_topic_size_lines
# set to 350, and adjust with experience.
$maximum_topic_size_lines = '';
$suggested_topic_size_lines = '';
	  

2.2.10. Comment Email Configuration

By default, whenever a comment it submitted, an email will be sent to the author of the comment, the author of the review, and anyone else who has submitted a comment on the line of code in question. This may not be appropriate for some team processes, and can be changed by setting $allow_comment_email to 0.

# If true, Codestriker will send out emails to the topic owner and
# comment submitter when a comment is added. If this option is false,
# no email will be sent to either the topic owner or the comment
# submitter. Emails about each comment may not be needed if a meeting
# is planned to discuss the topic. If the comment submitter specifies
# a cc user, an email is always sent out, regardless of this setting.
$allow_comment_email = 1;
	   

2.2.11. Source Code Hihglighting

Source code highlighting will be performed if the Highlight program is installed.

# Location of the highlight binary, which is used for highlighting source code.
# Available from http://www.andre-simon.de/.  If this is not set, no syntax
# highlighting will be performed.
$highlighter = '';
#$highlighter = '/usr/bin/highlight';
#$highlighter = 'C:/Program Files (x86)/WinHighlight/highlight.exe'; 
	  

2.2.12. Default View Topic File View Mode

As explained by the comments in the configuration file, it it possible to specify by default, whether topics display the deltas for all files in the review, or just a single file at a time by default. The viewing mode can be changed dynamically on the view topic screen.

# When displaying a topic, if this value is -1, then all files in the
# topic are displayed in the one page (default old Codestriker
# behaviour).  If the value is 0, then only the first file is shown,
# with links to display the other files.  This is useful for those
# deployments that review a large amount of code.
$default_file_to_view = -1;
	  

2.2.13. Comment Thread Metrics

As explained by the comments in the configuration file, it is possible to defined a number of metrics associated with each comment thread (issue) created in the review.

# Each comment thread (or issue) that is created against a specific
# code line in Codestriker can have a configurable number of
# user-defined metrics recorded against it.
#
# Every site has their own requirements, below are a number of example
# configurations.  The "name" attribute refers to the name of the
# metric being recorded.  The "values" attribute is a list of values
# that this metric can be assigned to.  The "default_value" attribute
# is optional, and indicates what the default value of the metric is
# assigned to.  If this attribute is not specified, then the user will
# be required to specify a value for a metric when creating a new
# comment thread.  This is recommended, so that users think about what
# these values should be, rather than blindly accepting default
# values.  For the "Status" metric below however, it is recording the
# "state" of the thread, so an initial state of "Submitted" is reasonable.
# For the other metrics below, an initial value makes no sense.
# Metric items can have an optional show_on_main_page list that will
# force the numbers of comments with the metric settings to be reported
# on the main page of codestriker. 
$comment_state_metrics =
    [ 
      { name             => 'Status', 
	values           => ['Submitted', 'Invalid', 'Completed'],
	default_value    => 'Submitted',
	show_on_mainpage => ['Submitted' ] 
      }
    ];

# Two metrics defined: Status and Type.
#$comment_state_metrics =
#    [
#      { name=>'Status', values=>['Submitted', 'Invalid', 'Completed'],
#	                default_value=>'Submitted' },
#      { name=>'Type', values=>['Style', 'Minor', 'Major', 'Severe'] }
#    ];
#
# Four metrics defined: Status, Level, Mode and Type.
#$comment_state_metrics =
#    [
#      { name=>'Status', values=>['Submitted', 'Invalid', 'Completed'],
#	                default_value=>'Submitted' },
#      { name=>'Level', values=>['Major', 'Minor'] },
#      { name=>'Mode', values=>['Missing', 'Wrong', 'Unclear', 'Suggestion'] },
#      { name=>'Type', values=>['Logic', 'Data Handling', 'Interface',
#			       'Error Handling', 'Performance', 'Comments',
#			       'Standards'] }
#    ];
#
# Case where no comment thread metrics are to be used.
#$comment_state_metrics = [];
	  

2.2.14. Metrics Support

As explained by the comments in the configuration file, it is possible to maintain software metrics obtained from the code reviewing process. There is also scope for customising Codestriker to track your own software metrics.

# This options configures the metric support in codestriker. You have
# the following options:
#
# $metric_config = "none", "basic", "all", "metric name, metric name, etc"
#
# "none" - turns off all extra metric support in the application. The
# metric page will only display and manage data that is strictly
# required to perform the review.  Codestriker will not require any
# addition data input from the reviewers and authors.  This is the
# default. However, you still get basic data like how many topics are
# being created and how problems are being found.
#
# "basic" - Turns on the metrics that are considered to be essential
# for a metric program. It will require that reviewers and authors
# enter the time spent reviewing the topic, the time spent in the
# review meeting, and the time spent preparing for the review. The
# metric selection assumes that you are following a formal review
# process with a preparation meeting, and a defect review meeting.
#   
#   kickoff time - time spent preparing for the review
#   checking time - time spent actually reviewing the topic.
#   logging meeting duration - the time spent in the logging meeting.
#
# "all" - Turns on all of the metrics that one could possibly want to
# track. The list of metrics is from the book "Software Inspection" by
# Gilb and Graham.  You should probably not use this unless you are
# using a formal process that is well established. You may want to
# enable this temporally to get a idea of the types of metrics that
# are supported.
#
# "name,name" - Lastly, you can pick and chose what metrics you would
# like to enable.  just list the metric names in a comma separated
# list. You can see all of the build in metrics in the
# lib/Codestriker.pm file. For example, if you don't hold a kick off
# meeting, and but do hold a logging meeting, the basic option will not
# quit fit. You should set the $metric_config as:
# $metric_config = "checking time,logging meeting duration".
#
# If you don't like our choices of metrics, the names, descriptions,
# etc feel free to edit the lib/Codestriker.pm. It contains
# documentations on how to add your own metrics into codestriker. It
# is easy to do, and does not require any coding.

$metric_config = "none";
	  

2.2.15. RSS Support

If you install the XML::RSS module, and re-run install.pl, Codestriker will display an RSS link on the topic list page, which can be used as a URL into your RSS reader, to keep track of new topics being added to the system.

2.2.16. Scmbug Integration

It is possible for Codestriker to integrate with ScmBug (http://www.mkgnu.net/?q=scmbug). This allows users to generate a topic based on the changes done under a given bug ID (or list of bug IDs). An example configuration is:

$scmbug_hostname = 'localhost';
$scmbug_port = 3872;
$scmbug_lib_dir = 'C:/Program Files/Scmbug/share/scmbug/lib';

This would match the default settings used by Scmbug on Windows. Where $scmbug_hostname and $scmbug_port are the host and port of the machine where Scmbug is running. The $scmbug_lib_dir points to the lib directory under the Scmbug installation. If Scmbug is running on a separate machine a copy of the Scmbug lib directory needs to be staged on the same machine as codestriker and the $scmbug_lib_dir variable made to point at this.