WebSVN – DevTools – /CodeStriker/trunk/html/x504.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Reviewing Topics</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 Topic"
HREF="x394.html"><LINK
REL="NEXT"
TITLE="Viewing Comments"
HREF="x602.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="x394.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="x602.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN504"
>3.5. Reviewing Topics</A
></H1
><P
>        Reviewing a topic is achieved by going to the "View Topic"
        screen for a specific review topic.  This can be accessed from
        either the "Topic List" screen (<A
HREF="x339.html"
>Section 3.2</A
>),
        or from a URL in a new topic notification email, which is sent
        to the author and reviewers.
      </P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="VIEW-TOPIC"
>3.5.1. Viewing a Topic</A
></H2
><P
>         The "View Topic" screen is one of four tabs available for
          viewing aspects of a topic.  An example "Topic Text" tab
          display can be seen in <A
HREF="x504.html#FIGURE-VIEWTOPIC"
>Figure 3-5</A
>.
          <DIV
CLASS="FIGURE"
><A
NAME="FIGURE-VIEWTOPIC"
></A
><P
><B
>Figure 3-5. View Topic Screenshot</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="viewtopic.png"></P
></DIV
></DIV
>
        </P
><P
>         The top bar contains the following links to other
          Codestriker pages:
          <P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>List open topics</DT
><DD
><P
>                 Following this link will take you to the "Topic
                  List" page (see <A
HREF="x339.html"
>Section 3.2</A
>), and
                  will display all open topics in the system.
                </P
></DD
><DT
>Create new topic</DT
><DD
><P
>                 Following this link will take you to the "Create
                  Topic" page (see <A
HREF="x394.html"
>Section 3.4</A
>).
                </P
></DD
><DT
>Search</DT
><DD
><P
>                 Following this link will take you to the "Topic
                  Search" page (see <A
HREF="x656.html"
>Section 3.9</A
>).
                </P
></DD
><DT
>Help</DT
><DD
><P
>                 Following this link will show this help text.
                </P
></DD
></DL
></DIV
>       
        </P
><P
>         The next part of the screen shows the four available tabs
          for viewing different aspects of a topic.  The "Topic
          Comments" tab is for viewing the comments that have been
          submitted against the topic.  Clicking on this tab will take
          you to the "Topic Comments" page (see <A
HREF="x602.html"
>Section 3.6</A
>).  The "Topic Properties" tab takes
          you to a page where you can view and edit the topic's
          attributes, such as the title, author,
          reviewer, the repository the code in the review has been
          made against, the project the review is associated with, and
          the topic description.  Clicking on this tab will take you
          to the "Topic Properties" page (see <A
HREF="x624.html"
>Section 3.7</A
>).  Finally the "Topic
          Information" tab contains topic metric data, both
          user-defined and entered, and those that can be
          automatically derived by Codestriker.  Clicking on this tab
          will take you to the "Topic Information" page (see <A
HREF="x637.html"
>Section 3.8</A
>).
        </P
><P
>         Following the "Download topic text" link
          will return in the browser the raw topic text
          which was entered when the review was created.  This can be
          useful if the raw diff needs to be retrieved, so it can be
          used as a patch file.  There are some links which affect the
          display, such as whether a mono-space font should be used to
          render the code changes (requires more screen real-estate),
          whether to preserve the code's line-breaking or not, and
          what tab-width to use.
        </P
><P
>         This is followed by the table of contents of the review,
          which consists of the list of files which comprise the
          topic, whether they are added, removed or modified
          files, appropriately colour-coded.
          If a file has been modified, the revision of the file that has been
          modified is displayed.  If filename is clicked, the browser will move to
          the anchor which corresponds to changes made to that file.
        </P
><P
>         The rest of the "View Topic" page can be seen in <A
HREF="x504.html#FIGURE-VIEWTOPICDETAIL"
>Figure 3-6</A
>.
          <DIV
CLASS="FIGURE"
><A
NAME="FIGURE-VIEWTOPICDETAIL"
></A
><P
><B
>Figure 3-6. View Topic Detail Screenshot</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="viewtopicdetail.png"></P
></DIV
></DIV
>
        </P
><P
>         This shows the start of the code changes for the file
          <TT
CLASS="FILENAME"
>codestriker/codestriker.pl</TT
>.  Clicking
          on the filename will show revision history of this file, if
          Codestriker has been configured to link with a system, like
          ViewCVS.  The "Go To Contents" link will move the browser
          back to the table of contents.
        </P
><P
>         From this point, the screen in split into two sections,
          where the left side represents the old version of the file,
          and right side represents the new version.  In the figure,
          the code in the block of red represents code which has been
          removed in the proposed change.  Adjacent yellow blocks
          represent code changes, as can be seen with the version
          number change.  The green block represents new code which
          has been added, in this instance, the new constants for
          viewing modes.
        </P
><P
>         Each file is broken up into a series of "deltas".  At the
          head of each delta block, for both the old and new versions
          of the file, there is an indication of what line number the
          delta started at.  In this situation, clicking on the "Line
          24" link on the left hand side, will open a new browser
          window, which will contain the complete original contents of
          <TT
CLASS="FILENAME"
>codestriker/codestriker.pl</TT
>, anchored at
          line 24.  Clicking on the "Line 22" link on the right hand
          side will contain the complete contents of
          <TT
CLASS="FILENAME"
>codestriker/codestriker.pl</TT
> will
          <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>all</I
></SPAN
> of the proposed changes applied.
          Clicking on "Parallel" will do a similar job, but will show
          both the original and new version of the complete file
          side-by-side.  See <A
HREF="x504.html#VIEW-FILE"
>Section 3.5.3</A
> for more
          details on what can be done with these complete file-based
          views, which can assist enormously in the review process.
        </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="ADD-COMMENT"
>3.5.2. Adding a Comment</A
></H2
><P
>         Every line of code in the display, is prefixed with a
          hyperlinked number.  This number represents the line number
          of the file.  If a comment needs to be made against a
          specific linenumber, click on the linenumber, and floating
          window will come up with the "Add Comment" page (see
          <A
HREF="x504.html#ADD-COMMENT"
>Section 3.5.2</A
>).  If a comment has already
          been made against a line, it will be red.  Hovering over
          the line will bring up a tooltip window, containing the
          details of the comment made.
        </P
><P
>         A comment against a line is made by clicking on the line
          number of interest.  This will display a floating window,
          an example can be seen in <A
HREF="x504.html#FIGURE-ADD-COMMENT"
>Figure 3-7</A
>.
          <DIV
CLASS="FIGURE"
><A
NAME="FIGURE-ADD-COMMENT"
></A
><P
><B
>Figure 3-7. Add Comment Screenshot</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="edittopic.png"></P
></DIV
></DIV
>
          As can be seen in the figure, the window contains a 
          text box where the comment can
          be entered.  Any formatting will be preserved, so that you
          can enter new code fragments, if required.  Any comment
          metrics defined in the Codestriker configuration will appear
          here as a series of dropdown boxes.  In this example, there
          is only the comment metric "Status" defined.  As before,
          your email address is remembered in the browser's cookie, to
          prevent you from having to enter it each time you make a
          comment.  When the "Submit" button is pressed, an email will
          be generated and sent to the author of the review, to the
          email address in the "Your email address" field as a
          reference, to the email address in the "Cc" field, just in
          case there is a requirement to send the email elsewhere, and
          to any other email addresses that have made a comment on
          this line, so that it is possible to get a form of
          discussion happening.
          </P
><P
>         Once the comment has been accepted by the server, it will be
          automatically dismissed.  If there was an error processing
          the comment, an error message will be displayed at the top
          of the window.
        </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="VIEW-FILE"
>3.5.3. Viewing Complete old/new Files</A
></H2
><P
>         As mention in <A
HREF="x504.html#VIEW-TOPIC"
>Section 3.5.1</A
>, it is possible to
          view the entire contents of a file in a review in its
          original form, or in its proposed form, or side-by-side
          depending on whether the "Line" or "Parallel" link was
          selected.  The review has to be linked to a SCM repository,
          so that it can fetch parts of the file which aren't a part
          of the review text.
        </P
><P
>         When a "Line" link is clicked, a new browser window will
          come up with the contents of the file.  This will be slow
          the first time, but in
          subsequent times will be fast since the browser window is
          not closed.  An example of this window can be seen in <A
HREF="x504.html#FIGURE-VIEWFILE"
>Figure 3-8</A
>.
          <DIV
CLASS="FIGURE"
><A
NAME="FIGURE-VIEWFILE"
></A
><P
><B
>Figure 3-8. View File Screenshot</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="fileview.png"></P
></DIV
></DIV
>
        </P
><P
>         This view matches the new contents of
          <TT
CLASS="FILENAME"
>codestriker/codestriker.pl</TT
>, from the
          "View Topic" screen seen in <A
HREF="x504.html#VIEW-TOPIC"
>Section 3.5.1</A
>.
          Each corresponding delta will have consecutive hyperlinked
          line numbers.  Those lines which do not have a hyperlinked
          line number are outside the deltas in the review, but are a
          part of the file.  Clicking on a hyperlinked line will bring
          the "Add Comment" window into display, in the same way it
          would as if the line number was clicked from the "View
          Topic" screen.
        </P
><P
>         Seeing the entire contents of a file, either pre or post
          change is often essential to complete a review properly.
          Sometimes, it is necessary to see both versions of the file
          side-by-side.  An example can be seen in <A
HREF="x504.html#FIGURE-PARALLELFILEVIEW"
>Figure 3-9</A
>.
          <DIV
CLASS="FIGURE"
><A
NAME="FIGURE-PARALLELFILEVIEW"
></A
><P
><B
>Figure 3-9. Parallel View File Screenshot</B
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="parallelfileview.png"></P
></DIV
></DIV
>
          The same rules apply for adding comments - any hyperlinked
          line number can be clicked in order to add a comment.
        </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="x394.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="x602.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Creating a new Topic</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c333.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Viewing Comments</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Subversion Repositories DevTools

(root)/CodeStriker/trunk/html/x504.html – Rev 1308
