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 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.
3.4.2. 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.3. 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.4. 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.