Subversion Repositories DevTools

Rev

Rev 1295 | Blame | Compare with Previous | Last modification | View Log | RSS feed 

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Creating a new Topic</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="The Codestriker Guide"
HREF="book1.html"><LINK
REL="UP"
TITLE="User's Guide"
HREF="c333.html"><LINK
REL="PREVIOUS"
TITLE="Creating a new Project"
HREF="x370.html"><LINK
REL="NEXT"
TITLE="Reviewing Topics"
HREF="x504.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The Codestriker Guide: Version 1.9.3</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x370.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 3. User's Guide</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x504.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="CREATE-TOPIC"
>3.4. Creating a new Topic</A
></H1
><P
>        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 <A
HREF="x394.html#FIGURE-CREATE-TOPIC"
>Figure 3-4</A
>.  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
        <A
HREF="x339.html"
>Section 3.2</A
>).  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
        <TT
CLASS="FILENAME"
>SubmitCodeReview.pl</TT
> script in the
        <TT
CLASS="FILENAME"
>bin</TT
> directory in the Codestriker
        distribution.
        <DIV
CLASS="FIGURE"
><A
NAME="FIGURE-CREATE-TOPIC"
></A
><P
><B
>Figure 3-4. Create Topic Screenshot</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="createtopic.png"></P
></DIV
></DIV
>
      </P
><P
>        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 <A
HREF="x339.html"
>Section 3.2</A
>).  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.
      </P
><P
>        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.
      </P
><P
>        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.
      </P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN412"
>3.4.1. Creating CVS Diff Topics</A
></H2
><P
>         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:
          <PRE
CLASS="PROGRAMLISTING"
>% cvs diff -uN &#62; /tmp/review.txt
          </PRE
>
          This command creates a diff file, which consists of the code
          changes you have made since you checked out the project from
          CVS.  The <CODE
CLASS="OPTION"
>-u</CODE
> option indicates to create a
          "unidiff" formatted file, which is what Codestriker can
          parse.  The <CODE
CLASS="OPTION"
>-N</CODE
> 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
          <CODE
CLASS="OPTION"
>-u</CODE
> is specified, to ensure the diff is in
          unidiff format.  Note for reviews which include C/C++ code,
          you can also include the
          <CODE
CLASS="OPTION"
>--show-function-line</CODE
> and/or
          <CODE
CLASS="OPTION"
>--show-c-function</CODE
> options, which will
          indicate for each diff delta in the display, what function
          is being modified.
        </P
><P
>         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.
        </P
><P
>         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.
        </P
><P
>         Alternatively, Codestriker can also accept CVS diffs of
          already committed code from commands such as:
          <PRE
CLASS="PROGRAMLISTING"
>% cvs rdiff -uN -r START_TAG -r END_TAG MODULE
          </PRE
>
          Where 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.
        </P
><P
>         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
          <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>or</I
></SPAN
> 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:
          <PRE
CLASS="PROGRAMLISTING"
>% cvs rdiff -uN -r 1.0 -r TAG MODULE
          </PRE
>
        </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN428"
>3.4.2. Creating CVS Diff Topics Automatically</A
></H2
><P
>         Depending on your development process, it may be more
          convenient for CVS to automatically create a Codestriker
          topic <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>automatically</I
></SPAN
> 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.
        </P
><P
>         The standard <TT
CLASS="FILENAME"
>commit_prep.pl</TT
> and
          <TT
CLASS="FILENAME"
>log_accum.pl</TT
> 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.
          <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Unfortunately, these scripts can only be executed
          on the UNIX platform.</I
></SPAN
>
        </P
><P
>         The <TT
CLASS="FILENAME"
>commit_prep.pl</TT
> and
          <TT
CLASS="FILENAME"
>log_accum.pl</TT
> files are located in the
          Codestriker <TT
CLASS="FILENAME"
>bin</TT
> directory, and need to
          be copied into your <TT
CLASS="FILENAME"
>CVSROOT</TT
> directory,
          with a line like the following in your
          <TT
CLASS="FILENAME"
>commitinfo</TT
> file (read the comment in
          this file to set this correctly for your site):
          <PRE
CLASS="PROGRAMLISTING"
>DEFAULT $CVSROOT/CVSROOT/commit_prep.pl -r
          </PRE
>
          and a line like the following in your
          <TT
CLASS="FILENAME"
>loginfo</TT
> file (read the comment in this
          file to set this correctly for your site):
          <PRE
CLASS="PROGRAMLISTING"
>DEFAULT $CVSROOT/CVSROOT/log_accum.pl %s
          </PRE
>
           The <TT
CLASS="FILENAME"
>log_accum.pl</TT
> 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 <TT
CLASS="FILENAME"
>$CVSROOT/CVSROOT/commitlogs</TT
>
           directory with the appropriate user-writable permissions,
           as commit information is written here as a result of these
           scripts running.
         </P
><P
>          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.
         </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN448"
>3.4.3. Creating Diff Topics</A
></H2
><P
>         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:
          <PRE
CLASS="PROGRAMLISTING"
>% diff -urN ../old-version/ . &#62; /tmp/review.txt
          </PRE
>
          Like the CVS command shown above, the <CODE
CLASS="OPTION"
>-u</CODE
>
          and <CODE
CLASS="OPTION"
>-N</CODE
> options are specified to output a
          unidiff file, which contains new and old files.  The
          <CODE
CLASS="OPTION"
>-r</CODE
> option indicates to recursively check
          the source and target directories specified (in this case
          <TT
CLASS="FILENAME"
>../old-version</TT
> and
          <TT
CLASS="FILENAME"
>.</TT
> to find differences.  There are
          likely to be other options that will be specified, run
          <B
CLASS="COMMAND"
>man diff</B
> for more options.  Note for
          reviews which include C/C++ code, you can also include the
          <CODE
CLASS="OPTION"
>--show-function-line</CODE
> and/or
          <CODE
CLASS="OPTION"
>--show-c-function</CODE
> options, which will
          indicate for each diff delta in the display, what function
          is being modified.
        </P
><P
>         The "Start tag", "End tag" and "Module" fields have no
          relevance in this situation.
        </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN461"
>3.4.4. Creating Plain Text Topics</A
></H2
><P
>         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.
        </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN464"
>3.4.5. Creating Subversion Diff Topics</A
></H2
><P
>         Similar to CVS, Subversion diffs are created by again, going
          to the top of your project directory, and issuing the
          following command:
          <PRE
CLASS="PROGRAMLISTING"
>% svn diff -N &#62; /tmp/review.txt
          </PRE
>
          This 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 <B
CLASS="COMMAND"
>svn diff</B
>
          command <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>outside</I
></SPAN
> 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
          <B
CLASS="COMMAND"
>svn diff</B
>.
        </P
><P
>         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 <B
CLASS="COMMAND"
>svn
          diff</B
> 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:
          <PRE
CLASS="PROGRAMLISTING"
>% svn diff --non-interactive -r START_TAG:END_TAG --old repository_url MODULE
          </PRE
>
          In 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.
        </P
><P
>         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.
        </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN475"
>3.4.6. Creating Perforce Diff Topics</A
></H2
><P
>         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:
          <PRE
CLASS="PROGRAMLISTING"
>% p4 diff -du &#62; /tmp/review.txt
          </PRE
>
          This 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.
        </P
><P
>         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:
          <PRE
CLASS="PROGRAMLISTING"
>% p4 describe -du 132 &#62; /tmp/review.txt
          </PRE
>
          Here 132 is the change-number.  This should be substituted
          with the change-number that you want to review.
        </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN481"
>3.4.7. Creating ClearCase Diff Topics</A
></H2
><P
>          In its very basic form, a ClearCase diff file can be created
          for a single file using the following command:
          <PRE
CLASS="PROGRAMLISTING"
>% cleartool diff -serial_format -predecessor filename &#62; /tmp/review.txt
          </PRE
>
          This 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:
          <PRE
CLASS="PROGRAMLISTING"
>% cleartool lsco -cview -short -recurse
          </PRE
>
       </P
><P
>          Combine the two commands together to generate a single
          file with all modified files can be achieved doing something
          like:
          <PRE
CLASS="PROGRAMLISTING"
>% cleartool lsco -cview -short -recurse | \
  xargs -n1 cleartool diff -serial_format -predecessor &#62; /tmp/review.txt
          </PRE
>
          Note 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:
          <PRE
CLASS="PROGRAMLISTING"
>% cleartool lsco -cview -short -recurse | sed 's/\\/\//g' | \
  xargs -n1 cleartool diff -serial_format -predecessor &#62; /tmp/review.txt
          </PRE
>
       </P
><P
>         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
         <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>top-level directory</I
></SPAN
> 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.
       </P
><P
>        Note the above commands can be modified if there is
         only interest in a specific sub-directory in your view, for
         example, the
         <B
CLASS="COMMAND"
>cleartool lsco</B
> can be amended with the
         sub-directory of interest as follows:
          <PRE
CLASS="PROGRAMLISTING"
>% cleartool lsco -cview -short -recurse pathname/to/interested/dir | \
  xargs -n1 cleartool diff -serial_format -predecessor &#62; /tmp/review.txt
          </PRE
>
        </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN494"
>3.4.8. Creating Visual SourceSafe Topics</A
></H2
><P
>         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:
          <PRE
CLASS="PROGRAMLISTING"
>C:\Project\&#62; ssdiff.pl &#62; topic.txt
          </PRE
>
          The <TT
CLASS="FILENAME"
>topic.txt</TT
> 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.  
        </P
><P
>         The <TT
CLASS="FILENAME"
>ssdiff.pl</TT
> Perl script is a custom
          script that is contained in the Codestriker
          <TT
CLASS="FILENAME"
>bin</TT
> 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.
        </P
><P
>         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 <TT
CLASS="FILENAME"
>$/Project/Gui</TT
>,
          which would work on all files located within that path.
        </P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x370.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x504.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Creating a new Project</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c333.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Reviewing Topics</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>