3.4. Creating a new Topic
The "Create topic" screen can be accessed from a number of other screens, and requires the submission of a number of details in order to create a topic. A screenshot can be seen in Figure 3-4. It is also possible to create a new topic which obsoletes a number of other topics via the "Obsolete Topics" button on the topic list screen (see Section 3.2). This is normally done when a review has many comments, and a new review (which obsoletes the old review) needs to be created which has addressed these comments. It is also possible to generate new topics from the command line. Check out the SubmitCodeReview.pl script in the bin directory in the Codestriker distribution.
The topic title is a mandatory field which contains a one-line summary of the topic. This title is used when the topic is displayed in the "Topic list" screen (see Section 3.2). The topic description contains a more detailed description of the review itself, and should be enough for a reviewer to understand the purpose of the review. If Codestriker is linked to a bug tracking system, further down in the form, the "Bug IDs" field gives the opportunity to enter in multiple bug ids (either space or comma separated), which will also give the reviewer an opportunity to see what bugs this review fixes.
The "Project" dropdown list should be selected onto the project this review belongs to. The last three fields contain comma-separated email addresses. The "Your email address" field contains the email address which will receive review comments. This is typically, the author's email address. The "Reviewers" field contains the list of reviewer email address which will be notified once the review is created. The "Cc" field is typically used for notifying a group email list that a new review has been created. These field values are stored into your browser's cookie, so that the next time a review is created, these fields will be pre-filled, as they don't typically change much between different reviews.
The most complex part of this form are the values required for the "Topic text upload", "Start tag", "End tag", "Module" and "Repository" fields. These fields dictate what the actual review text is. The first step is to select what source control management system the review was made against, and updating the "Repository" field accordingly. The following sub-sections detail the different review inputs that can be handled. Once all the details have been entered, and the "Submit" button is pressed, a confirmation screen will come up indicating that the review has been created. An email, with a URL to view the topic will be sent to the author, reviewers and any email addresses entered in the "Cc" field.
3.4.1. Creating CVS Diff Topics
For CVS projects, a common situation is you have a checkout of your project's module, and you have fixed a bug which needs to be reviewed. To get this reviewed in Codestriker, you need to generate the review text, by going to the top-level directory of your checkout, and issuing a command like:
% cvs diff -uN > /tmp/review.txtThis command creates a diff file, which consists of the code changes you have made since you checked out the project from CVS. The
-u option indicates to create a
"unidiff" formatted file, which is what Codestriker can
parse. The -N option means to show added
and removed files. Depending on your development process,
you may want to issue different cvs diff commands with
different flags, or even using "cvs rdiff" instead.
Codestriker can accept any input, as long as
-u is specified, to ensure the diff is in
unidiff format. Note for reviews which include C/C++ code,
you can also include the
--show-function-line and/or
--show-c-function options, which will
indicate for each diff delta in the display, what function
is being modified.
This filename can either be entered directly into the "Topic text upload" field, or selected from a file dialog which is created when the "Browse" button is pressed. The "Start tag", "End tag" and "Module" fields can be left blank. Once all the other fields have been entered, clicking the "Submit" button will create the review, and show a confirmation screen.
In some development processes, CVS tags are used to mark units of work that have been applied to the repository. Rather than generating the review text via a CVS command, as specified in the previously, the review text can be specified by entering in the "Start tag", "End tag" and "Module" name into their respective fields. Codestriker will then fetch the review text from the nominated repository automatically, by executing the appropriate CVS command itself.
Alternatively, Codestriker can also accept CVS diffs of already committed code from commands such as:
% cvs rdiff -uN -r START_TAG -r END_TAG MODULEWhere START_TAG, END_TAG and MODULE are substituted with appropriate values. Note this is no different to what Codestriker does when values are entered into the "Start tag", "End Tag" and "Module" fields when creating a topic.
If you want to review code in its full form as it exists in the repository for a specific tag value, you only need to specify this tag value in either the START_TAG or END_TAG field, and an appropriate value in the MODULE field. Codestriker will fetch all of the source files for this module and tag into the topic, and treat all of the files as "new" (ie, no diffs). This is no different to executing the following command to generate a diff:
% cvs rdiff -uN -r 1.0 -r TAG MODULE
3.4.2. Creating CVS Diff Topics Automatically
Depending on your development process, it may be more convenient for CVS to automatically create a Codestriker topic automatically whenever a commit occurs. The benefit with this approach is developers don't need to explicitly create code reviews. A "code reviewer" can then monitor all commits to the repository, and has the opportunity to send comments to the authors if they spot any issues that need addressing.
The standard commit_prep.pl and log_accum.pl scripts from CVS have been modified so that the email which is sent after each commit which contains the diff of the commit, also includes the URL of the associated Codestriker topic that was created. Unfortunately, these scripts can only be executed on the UNIX platform.
The commit_prep.pl and log_accum.pl files are located in the Codestriker bin directory, and need to be copied into your CVSROOT directory, with a line like the following in your commitinfo file (read the comment in this file to set this correctly for your site):
DEFAULT $CVSROOT/CVSROOT/commit_prep.pl -r
and a line like the following in your
loginfo file (read the comment in this
file to set this correctly for your site):
DEFAULT $CVSROOT/CVSROOT/log_accum.pl %s
The log_accum.pl file needs to have
some configuration variables set at the start of the script
to reflect your site. You will also need to make sure you
create a $CVSROOT/CVSROOT/commitlogs
directory with the appropriate user-writable permissions,
as commit information is written here as a result of these
scripts running.
Note the first line of the log message will be used as the topic title. The entire log message is used as the topic description. Any strings of the form "Bug nnn" in the log message will be taken as a reference to a bug id, and will be used in the topic's bugid field.
3.4.3. Creating Diff Topics
In some deployments, there may not even be a source control management system, and it might be the case that only diffs are reviewed. An example command to generate the review text could be something like:
% diff -urN ../old-version/ . > /tmp/review.txtLike the CVS command shown above, the
-u
and -N options are specified to output a
unidiff file, which contains new and old files. The
-r option indicates to recursively check
the source and target directories specified (in this case
../old-version and
. to find differences. There are
likely to be other options that will be specified, run
man diff for more options. Note for
reviews which include C/C++ code, you can also include the
--show-function-line and/or
--show-c-function options, which will
indicate for each diff delta in the display, what function
is being modified.
The "Start tag", "End tag" and "Module" fields have no relevance in this situation.
3.4.4. Creating Plain Text Topics
It is also possible to use Codestriker to simply review text that is not in the form as a diff. In this situation, Codestriker will simply treat the text as a single new file. Reviewers will still be able to view the text and make comments on a per-line basis as before. Simply put the filename to be reviewed in the "Topic text upload" field. The "Start tag", "End tag" and "Module" fields have no relevance in this situation.
3.4.5. Creating Subversion Diff Topics
Similar to CVS, Subversion diffs are created by again, going to the top of your project directory, and issuing the following command:
% svn diff -N > /tmp/review.txtThis file should then be selected for the "Topic text upload" field. The "Start tag", "End tag" and "Module" fields have no relevance in this situation. Because of an issue in Subversion, running the svn diff command outside of the repository root will not allow Codestriker to download and review the full file (although the patch segments can still be reviewed). If you commit your code first, then let Codestriker make the diff, as explained in the next section, then you can avoid this limitation. If you really don't want to commit your code, you will need to modify the diff file to include the paths on the Index: +++, and --- lines generated by svn diff.
In some development processes, branches are used as the logical unit of work that should be reviewed. Rather than generating the review text via the svn diff command, as specified in the previous section, the review text can be created by setting the appropriate values into the "Start tag", "End tag" and "Module" fields. Codestriker will then fetch the review text from the nominated repository automatically, by executing the following command:
% svn diff --non-interactive -r START_TAG:END_TAG --old repository_url MODULEIn Subversion the tags can be a repository revision number or HEAD, The HEAD shortcut indicates the latest revision number in the repository. If you would like to review a specific single check in, for example, check in 544, then you would use 543 for START_TAG and 544 for END_TAG.
If you would like to review a branch before merging then enter the start tag as the version number of the branch creation. The end tag should be HEAD, and the module path should be the path into the branch directory relative to the repository location. All topics created by Codestriker have a builtin workaround for the Subversion diff problem.
3.4.6. Creating Perforce Diff Topics
Similar to CVS, Perforce diffs are created by going to the top of your checkout (or client view in Perforce terminology) and issuing a command like:
% p4 diff -du > /tmp/review.txtThis file should then be selected for the "Topic text upload" field. The "Start tag", "End tag" and "Module" fields have no relevance in this situation.
Alternatively, for code which has already been committed into the repository (or depot in Perforce terminology), a command like the following can be used to generate the topic text:
% p4 describe -du 132 > /tmp/review.txtHere 132 is the change-number. This should be substituted with the change-number that you want to review.
It is also possible to create Perforce topics from already committed code. Simply enter the change number into either the "Start tag" or "End tag" field, and set "Module" to be //, which corresponds to the root of the depot.
3.4.7. Creating ClearCase Diff Topics
In its very basic form, a ClearCase diff file can be created for a single file using the following command:
% cleartool diff -serial_format -predecessor filename > /tmp/review.txtThis file can then be uploaded into Codestriker for reviewing. Of course, it is far more useful to be able to review a group of files at once. In ClearCase, to determine which files are a part of a view, you can use the following command from the top level of your checkout:
% cleartool lsco -cview -short -recurse
Combine the two commands together to generate a single file with all modified files can be achieved doing something like:
% cleartool lsco -cview -short -recurse | \ xargs -n1 cleartool diff -serial_format -predecessor > /tmp/review.txtNote if you are on a Win32 platform, and you have cygwin installed, you may need to add an intermediate sed command so that cleartool doesn't complain:
% cleartool lsco -cview -short -recurse | sed 's/\\/\//g' | \ xargs -n1 cleartool diff -serial_format -predecessor > /tmp/review.txt
In all of the above commands, if a ClearCase repository has been specified in the Codestriker configuration, it is important that the above commands are run from the top-level directory of the view, so that the full vob pathname information is available within the diff files. This allows Codestriker to retrieve the full contents of files from the vob, so that a reviewer can see the changes applied to an entire file, rather than a small segment.
Note the above commands can be modified if there is only interest in a specific sub-directory in your view, for example, the cleartool lsco can be amended with the sub-directory of interest as follows:
% cleartool lsco -cview -short -recurse pathname/to/interested/dir | \ xargs -n1 cleartool diff -serial_format -predecessor > /tmp/review.txt
3.4.8. Creating Visual SourceSafe Topics
Similar to CVS, SourceSafe diffs are creating by going to the top of your project, and issuing a command like the following in a cmd.exe window:
C:\Project\> ssdiff.pl > topic.txtThe topic.txt file will contain the source-code differences made with the current code set compared with the SourceSafe repository. This file can then be selected for the "Topic text upload" field in the create topic screen. The "Start tag", "End tag" and "Module" fields have no relevance in this situation.
The ssdiff.pl Perl script is a custom script that is contained in the Codestriker bin directory, which needs to be installed on client machines that need to run the above command. The configuration section at the start of the script should be updated appropriately before it is used.
Alternatively, for code which has already been committed to SourceSafe, it is possible to explicitly specify on the create topic screen, values for the "Start tag", "End tag" and "Module" fields, which will enable Codestriker to fetch the topic text directly from SourceSafe. In this instance, any SourceSafe label names can be used in the tag fields. If only one tag field is specified, the complete contents of files corresponding to the specified label will be retrieved. The "Module" field contains a path into the SourceSafe repository which indicates the files of interest. An example value could be $/Project/Gui, which would work on all files located within that path.
3.4.9. Creating Topics from Bug IDs
If you have Codestriker configured to make use of Scmbug integration it is possible to generate a Topic by entering a list of bug IDs (comma separated). To generate the topic in this way, ensure that the Start Tag, End Tag and Module fields are left blank and that the relevant bug IDs are entered into the Bug IDs field.