Subversion Repositories DevTools

Rev

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

Rev Author Line No. Line
1293 dpurdie 1 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
2 
<HTML
3 
><HEAD
4 
><TITLE
5 
>Reviewing Topics</TITLE
6 
><META
7 
NAME="GENERATOR"
8 
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9 
REL="HOME"
10 
TITLE="The Codestriker Guide"
11 
HREF="book1.html"><LINK
12 
REL="UP"
13 
TITLE="User's Guide"
14 
HREF="c333.html"><LINK
15 
REL="PREVIOUS"
16 
TITLE="Creating a new Topic"
17 
HREF="x394.html"><LINK
18 
REL="NEXT"
19 
TITLE="Viewing Comments"
20 
HREF="x602.html"></HEAD
21 
><BODY
22 
CLASS="SECT1"
23 
BGCOLOR="#FFFFFF"
24 
TEXT="#000000"
25 
LINK="#0000FF"
26 
VLINK="#840084"
27 
ALINK="#0000FF"
28 
><DIV
29 
CLASS="NAVHEADER"
30 
><TABLE
31 
SUMMARY="Header navigation table"
32 
WIDTH="100%"
33 
BORDER="0"
34 
CELLPADDING="0"
35 
CELLSPACING="0"
36 
><TR
37 
><TH
38 
COLSPAN="3"
39 
ALIGN="center"
40 
>The Codestriker Guide: Version 1.9.3</TH
41 
></TR
42 
><TR
43 
><TD
44 
WIDTH="10%"
45 
ALIGN="left"
46 
VALIGN="bottom"
47 
><A
48 
HREF="x394.html"
49 
ACCESSKEY="P"
50 
>Prev</A
51 
></TD
52 
><TD
53 
WIDTH="80%"
54 
ALIGN="center"
55 
VALIGN="bottom"
56 
>Chapter 3. User's Guide</TD
57 
><TD
58 
WIDTH="10%"
59 
ALIGN="right"
60 
VALIGN="bottom"
61 
><A
62 
HREF="x602.html"
63 
ACCESSKEY="N"
64 
>Next</A
65 
></TD
66 
></TR
67 
></TABLE
68 
><HR
69 
ALIGN="LEFT"
70 
WIDTH="100%"></DIV
71 
><DIV
72 
CLASS="SECT1"
73 
><H1
74 
CLASS="SECT1"
75 
><A
76 
NAME="AEN504"
77 
>3.5. Reviewing Topics</A
78 
></H1
79 
><P
80 
>        Reviewing a topic is achieved by going to the "View Topic"
81 
        screen for a specific review topic.  This can be accessed from
82 
        either the "Topic List" screen (<A
83 
HREF="x339.html"
84 
>Section 3.2</A
85 
>),
86 
        or from a URL in a new topic notification email, which is sent
87 
        to the author and reviewers.
88 
      </P
89 
><DIV
90 
CLASS="SECT2"
91 
><H2
92 
CLASS="SECT2"
93 
><A
94 
NAME="VIEW-TOPIC"
95 
>3.5.1. Viewing a Topic</A
96 
></H2
97 
><P
98 
>	  The "View Topic" screen is one of four tabs available for
99 
          viewing aspects of a topic.  An example "Topic Text" tab
100 
          display can be seen in <A
101 
HREF="x504.html#FIGURE-VIEWTOPIC"
102 
>Figure 3-5</A
103 
>.
104 
	  <DIV
105 
CLASS="FIGURE"
106 
><A
107 
NAME="FIGURE-VIEWTOPIC"
108 
></A
109 
><P
110 
><B
111 
>Figure 3-5. View Topic Screenshot</B
112 
></P
113 
><DIV
114 
CLASS="MEDIAOBJECT"
115 
><P
116 
><IMG
117 
SRC="viewtopic.png"></P
118 
></DIV
119 
></DIV
120 
>
121 
	</P
122 
><P
123 
>	  The top bar contains the following links to other
124 
	  Codestriker pages:
125 
	  <P
126 
></P
127 
><DIV
128 
CLASS="VARIABLELIST"
129 
><DL
130 
><DT
131 
>List open topics</DT
132 
><DD
133 
><P
134 
>		  Following this link will take you to the "Topic
135 
		  List" page (see <A
136 
HREF="x339.html"
137 
>Section 3.2</A
138 
>), and
139 
		  will display all open topics in the system.
140 
	        </P
141 
></DD
142 
><DT
143 
>Create new topic</DT
144 
><DD
145 
><P
146 
>		  Following this link will take you to the "Create
147 
		  Topic" page (see <A
148 
HREF="x394.html"
149 
>Section 3.4</A
150 
>).
151 
	        </P
152 
></DD
153 
><DT
154 
>Search</DT
155 
><DD
156 
><P
157 
>		  Following this link will take you to the "Topic
158 
		  Search" page (see <A
159 
HREF="x656.html"
160 
>Section 3.9</A
161 
>).
162 
	        </P
163 
></DD
164 
><DT
165 
>Help</DT
166 
><DD
167 
><P
168 
>		  Following this link will show this help text.
169 
	        </P
170 
></DD
171 
></DL
172 
></DIV
173 
>
174 
	</P
175 
><P
176 
>	  The next part of the screen shows the four available tabs
177 
	  for viewing different aspects of a topic.  The "Topic
178 
	  Comments" tab is for viewing the comments that have been
179 
	  submitted against the topic.  Clicking on this tab will take
180 
	  you to the "Topic Comments" page (see <A
181 
HREF="x602.html"
182 
>Section 3.6</A
183 
>).  The "Topic Properties" tab takes
184 
	  you to a page where you can view and edit the topic's
185 
	  attributes, such as the title, author,
186 
	  reviewer, the repository the code in the review has been
187 
	  made against, the project the review is associated with, and
188 
	  the topic description.  Clicking on this tab will take you
189 
	  to the "Topic Properties" page (see <A
190 
HREF="x624.html"
191 
>Section 3.7</A
192 
>).  Finally the "Topic
193 
	  Information" tab contains topic metric data, both
194 
	  user-defined and entered, and those that can be
195 
	  automatically derived by Codestriker.  Clicking on this tab
196 
	  will take you to the "Topic Information" page (see <A
197 
HREF="x637.html"
198 
>Section 3.8</A
199 
>).
200 
        </P
201 
><P
202 
>	  Following the "Download topic text" link
203 
	  will return in the browser the raw topic text
204 
	  which was entered when the review was created.  This can be
205 
	  useful if the raw diff needs to be retrieved, so it can be
206 
	  used as a patch file.  There are some links which affect the
207 
	  display, such as whether a mono-space font should be used to
208 
	  render the code changes (requires more screen real-estate),
209 
	  whether to preserve the code's line-breaking or not, and
210 
	  what tab-width to use.
211 
	</P
212 
><P
213 
>	  This is followed by the table of contents of the review,
214 
	  which consists of the list of files which comprise the
215 
	  topic, whether they are added, removed or modified
216 
	  files, appropriately colour-coded.
217 
	  If a file has been modified, the revision of the file that has been
218 
	  modified is displayed.  If filename is clicked, the browser will move to
219 
	  the anchor which corresponds to changes made to that file.
220 
	</P
221 
><P
222 
>	  The rest of the "View Topic" page can be seen in <A
223 
HREF="x504.html#FIGURE-VIEWTOPICDETAIL"
224 
>Figure 3-6</A
225 
>.
226 
	  <DIV
227 
CLASS="FIGURE"
228 
><A
229 
NAME="FIGURE-VIEWTOPICDETAIL"
230 
></A
231 
><P
232 
><B
233 
>Figure 3-6. View Topic Detail Screenshot</B
234 
></P
235 
><DIV
236 
CLASS="MEDIAOBJECT"
237 
><P
238 
><IMG
239 
SRC="viewtopicdetail.png"></P
240 
></DIV
241 
></DIV
242 
>
243 
        </P
244 
><P
245 
>	  This shows the start of the code changes for the file
246 
	  <TT
247 
CLASS="FILENAME"
248 
>codestriker/codestriker.pl</TT
249 
>.  Clicking
250 
	  on the filename will show revision history of this file, if
251 
	  Codestriker has been configured to link with a system, like
252 
	  ViewCVS.  The "Go To Contents" link will move the browser
253 
	  back to the table of contents.
254 
	</P
255 
><P
256 
>	  From this point, the screen in split into two sections,
257 
	  where the left side represents the old version of the file,
258 
	  and right side represents the new version.  In the figure,
259 
	  the code in the block of red represents code which has been
260 
	  removed in the proposed change.  Adjacent yellow blocks
261 
	  represent code changes, as can be seen with the version
262 
	  number change.  The green block represents new code which
263 
	  has been added, in this instance, the new constants for
264 
	  viewing modes.
265 
	</P
266 
><P
267 
>	  Each file is broken up into a series of "deltas".  At the
268 
	  head of each delta block, for both the old and new versions
269 
	  of the file, there is an indication of what line number the
270 
	  delta started at.  In this situation, clicking on the "Line
271 
	  24" link on the left hand side, will open a new browser
272 
	  window, which will contain the complete original contents of
273 
	  <TT
274 
CLASS="FILENAME"
275 
>codestriker/codestriker.pl</TT
276 
>, anchored at
277 
	  line 24.  Clicking on the "Line 22" link on the right hand
278 
	  side will contain the complete contents of
279 
	  <TT
280 
CLASS="FILENAME"
281 
>codestriker/codestriker.pl</TT
282 
> will
283 
	  <SPAN
284 
CLASS="emphasis"
285 
><I
286 
CLASS="EMPHASIS"
287 
>all</I
288 
></SPAN
289 
> of the proposed changes applied.
290 
	  Clicking on "Parallel" will do a similar job, but will show
291 
	  both the original and new version of the complete file
292 
	  side-by-side.  See <A
293 
HREF="x504.html#VIEW-FILE"
294 
>Section 3.5.3</A
295 
> for more
296 
	  details on what can be done with these complete file-based
297 
	  views, which can assist enormously in the review process.
298 
	</P
299 
></DIV
300 
><DIV
301 
CLASS="SECT2"
302 
><H2
303 
CLASS="SECT2"
304 
><A
305 
NAME="ADD-COMMENT"
306 
>3.5.2. Adding a Comment</A
307 
></H2
308 
><P
309 
>	  Every line of code in the display, is prefixed with a
310 
	  hyperlinked number.  This number represents the line number
311 
	  of the file.  If a comment needs to be made against a
312 
	  specific linenumber, click on the linenumber, and floating
313 
	  window will come up with the "Add Comment" page (see
314 
	  <A
315 
HREF="x504.html#ADD-COMMENT"
316 
>Section 3.5.2</A
317 
>).  If a comment has already
318 
          been made against a line, it will be red.  Hovering over
319 
          the line will bring up a tooltip window, containing the
320 
          details of the comment made.
321 
	</P
322 
><P
323 
>	  A comment against a line is made by clicking on the line
324 
	  number of interest.  This will display a floating window,
325 
	  an example can be seen in <A
326 
HREF="x504.html#FIGURE-ADD-COMMENT"
327 
>Figure 3-7</A
328 
>.
329 
	  <DIV
330 
CLASS="FIGURE"
331 
><A
332 
NAME="FIGURE-ADD-COMMENT"
333 
></A
334 
><P
335 
><B
336 
>Figure 3-7. Add Comment Screenshot</B
337 
></P
338 
><DIV
339 
CLASS="MEDIAOBJECT"
340 
><P
341 
><IMG
342 
SRC="edittopic.png"></P
343 
></DIV
344 
></DIV
345 
>
346 
	  As can be seen in the figure, the window contains a
347 
          text box where the comment can
348 
          be entered.  Any formatting will be preserved, so that you
349 
          can enter new code fragments, if required.  Any comment
350 
          metrics defined in the Codestriker configuration will appear
351 
          here as a series of dropdown boxes.  In this example, there
352 
          is only the comment metric "Status" defined.  As before,
353 
          your email address is remembered in the browser's cookie, to
354 
          prevent you from having to enter it each time you make a
355 
          comment.  When the "Submit" button is pressed, an email will
356 
          be generated and sent to the author of the review, to the
357 
          email address in the "Your email address" field as a
358 
          reference, to the email address in the "Cc" field, just in
359 
          case there is a requirement to send the email elsewhere, and
360 
          to any other email addresses that have made a comment on
361 
          this line, so that it is possible to get a form of
362 
          discussion happening.
363 
          </P
364 
><P
365 
>	  Once the comment has been accepted by the server, it will be
366 
          automatically dismissed.  If there was an error processing
367 
          the comment, an error message will be displayed at the top
368 
          of the window.
369 
	</P
370 
></DIV
371 
><DIV
372 
CLASS="SECT2"
373 
><H2
374 
CLASS="SECT2"
375 
><A
376 
NAME="VIEW-FILE"
377 
>3.5.3. Viewing Complete old/new Files</A
378 
></H2
379 
><P
380 
>	  As mention in <A
381 
HREF="x504.html#VIEW-TOPIC"
382 
>Section 3.5.1</A
383 
>, it is possible to
384 
	  view the entire contents of a file in a review in its
385 
	  original form, or in its proposed form, or side-by-side
386 
	  depending on whether the "Line" or "Parallel" link was
387 
	  selected.  The review has to be linked to a SCM repository,
388 
	  so that it can fetch parts of the file which aren't a part
389 
	  of the review text.
390 
	</P
391 
><P
392 
>	  When a "Line" link is clicked, a new browser window will
393 
	  come up with the contents of the file.  This will be slow
394 
          the first time, but in
395 
	  subsequent times will be fast since the browser window is
396 
	  not closed.  An example of this window can be seen in <A
397 
HREF="x504.html#FIGURE-VIEWFILE"
398 
>Figure 3-8</A
399 
>.
400 
	  <DIV
401 
CLASS="FIGURE"
402 
><A
403 
NAME="FIGURE-VIEWFILE"
404 
></A
405 
><P
406 
><B
407 
>Figure 3-8. View File Screenshot</B
408 
></P
409 
><DIV
410 
CLASS="MEDIAOBJECT"
411 
><P
412 
><IMG
413 
SRC="fileview.png"></P
414 
></DIV
415 
></DIV
416 
>
417 
	</P
418 
><P
419 
>	  This view matches the new contents of
420 
	  <TT
421 
CLASS="FILENAME"
422 
>codestriker/codestriker.pl</TT
423 
>, from the
424 
	  "View Topic" screen seen in <A
425 
HREF="x504.html#VIEW-TOPIC"
426 
>Section 3.5.1</A
427 
>.
428 
	  Each corresponding delta will have consecutive hyperlinked
429 
	  line numbers.  Those lines which do not have a hyperlinked
430 
	  line number are outside the deltas in the review, but are a
431 
	  part of the file.  Clicking on a hyperlinked line will bring
432 
	  the "Add Comment" window into display, in the same way it
433 
	  would as if the line number was clicked from the "View
434 
	  Topic" screen.
435 
	</P
436 
><P
437 
>	  Seeing the entire contents of a file, either pre or post
438 
	  change is often essential to complete a review properly.
439 
	  Sometimes, it is necessary to see both versions of the file
440 
	  side-by-side.  An example can be seen in <A
441 
HREF="x504.html#FIGURE-PARALLELFILEVIEW"
442 
>Figure 3-9</A
443 
>.
444 
	  <DIV
445 
CLASS="FIGURE"
446 
><A
447 
NAME="FIGURE-PARALLELFILEVIEW"
448 
></A
449 
><P
450 
><B
451 
>Figure 3-9. Parallel View File Screenshot</B
452 
></P
453 
><DIV
454 
CLASS="MEDIAOBJECT"
455 
><P
456 
><IMG
457 
SRC="parallelfileview.png"></P
458 
></DIV
459 
></DIV
460 
>
461 
	  The same rules apply for adding comments - any hyperlinked
462 
	  line number can be clicked in order to add a comment.
463 
	</P
464 
></DIV
465 
></DIV
466 
><DIV
467 
CLASS="NAVFOOTER"
468 
><HR
469 
ALIGN="LEFT"
470 
WIDTH="100%"><TABLE
471 
SUMMARY="Footer navigation table"
472 
WIDTH="100%"
473 
BORDER="0"
474 
CELLPADDING="0"
475 
CELLSPACING="0"
476 
><TR
477 
><TD
478 
WIDTH="33%"
479 
ALIGN="left"
480 
VALIGN="top"
481 
><A
482 
HREF="x394.html"
483 
ACCESSKEY="P"
484 
>Prev</A
485 
></TD
486 
><TD
487 
WIDTH="34%"
488 
ALIGN="center"
489 
VALIGN="top"
490 
><A
491 
HREF="book1.html"
492 
ACCESSKEY="H"
493 
>Home</A
494 
></TD
495 
><TD
496 
WIDTH="33%"
497 
ALIGN="right"
498 
VALIGN="top"
499 
><A
500 
HREF="x602.html"
501 
ACCESSKEY="N"
502 
>Next</A
503 
></TD
504 
></TR
505 
><TR
506 
><TD
507 
WIDTH="33%"
508 
ALIGN="left"
509 
VALIGN="top"
510 
>Creating a new Topic</TD
511 
><TD
512 
WIDTH="34%"
513 
ALIGN="center"
514 
VALIGN="top"
515 
><A
516 
HREF="c333.html"
517 
ACCESSKEY="U"
518 
>Up</A
519 
></TD
520 
><TD
521 
WIDTH="33%"
522 
ALIGN="right"
523 
VALIGN="top"
524 
>Viewing Comments</TD
525 
></TR
526 
></TABLE
527 
></DIV
528 
></BODY
529 
></HTML
530 
>