blob: 05504269ceabaae7d5cf6f6e8a79792b630b2d40 [file] [log] [blame]
<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>R4E Documentation - Concepts</title>
<link type="text/css" rel="stylesheet" href="book.css"/>
</head>
<body>
<table class="navigation" style="width: 100%;" border="0" summary="navigation">
<tr>
<th style="width: 100%" align="center" colspan="3">Concepts</th>
</tr>
<tr>
<td style="width: 20%" align="left">
<a href="_r4eOpenUser.html" title="Getting Started">
<img alt="Previous" border="0" src="images/prev.gif"/>
</a>
</td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right">
<a href="Tasks.html" title="Tasks">
<img alt="Next" border="0" src="images/next.gif"/>
</a>
</td>
</tr>
<tr>
<td style="width: 20%" align="left" valign="top">Getting Started</td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right" valign="top">Tasks</td>
</tr>
</table><hr/>
<h1 id="Concepts">Concepts</h1>
<h2 id="Basic_and_Informal_Reviews_workflows">Basic and Informal Reviews workflows</h2>
<p>R4E basic and informal reviews use a lightweight review process and can help to save time while performing reviews involving a small number of participants. It is also recommended to use them when using an agile methodology as development process. </p>
<p>The main difference between Basic and Informal Reviews is that there is no Anomaly state tracking in Basic reviews, while anomalies in Informal reviews are stateful and need to be closed in one way of another before the review can be completed. </p>
<p>The main differences of Basic and Informal reviews compared to Formal reviews are: </p>
<ul>
<li>There are no review phases. Reviews are either Active or Completed. </li>
<li>Anomalies can be created as long as the review is Active. For example, the author can create anomalies as soon as the review is created. </li>
<li>The decision meeting is not mandatory. </li>
<li>It is possible to notify the author/lead of progress in logging anomalies several times in a review. The author/lead can then start fixing some anomalies before the end of the review. </li>
<li>Anomalies are assigned to the author by default on a per review basis.</li>
</ul>
<p>There are several ways to perform basic and informal reviews since there are no formal review phases. The below picture describes a typical review that will be described in more detail. Dashed elements in the picture represent optional steps in this scenario. </p>
<p>
<br/>
</p>
<p>
<img border="0" src="BasicInformalReview.png"/>
</p>
<p>
<br/>
</p>
<h3 id="Create_new_review">Create new review</h3>
<p>In this scenario, the organizer wants artifacts to be reviewed by one colleague. The author first needs to create the review in R4E. As in formal reviews, this step involves naming the review, identifying participants/roles and identifying relevant input documentation. During the creation of the review, the organizer needs to specify that the review type is basic or informal. </p>
<h3 id="Identify_what_needs_to_be_reviewed">Identify what needs to be reviewed</h3>
<p>The organizer uses R4E to specify what needs to be reviewed. This step is performed like for formal reviews using R4E tools to automatically find artifact changes or by manually specifying portions of artifacts that need to be reviewed. The result is a collection of review items. </p>
<h3 id="Items_ready_for_review">Items ready for review</h3>
<p>The author notifies the reviewer that items are ready to be reviewed. This is done via an email notification that is generated from R4E. In this scenario, no formal meeting is scheduled. </p>
<h3 id="Review_item_examination.2C_anomaly.2Ftime_logging">Review item examination, anomaly/time logging</h3>
<p>The reviewer examines review items and logs anomalies. The time spent doing this activity can be logged in R4E in an iterative way (e.g. every day). </p>
<h3 id="Progress_notification">Progress notification</h3>
<p>In this scenario, the reviewer has completed a significant portion of the review (for example, a module/subsystem/feature) and wants to immediately inform the author about it. R4E is used to send a progress notification via an email containing the progress details to the author. Several progress notifications can be sent in a given review. </p>
<h3 id="Examine_and_fix.2Freject_anomalies">Examine and fix/reject anomalies</h3>
<p>The author relies on the progress notification information to start the anomaly examination. As a result, anomalies can either be accepted or rejected. Accepted anomalies can then be fixed. </p>
<h3 id="Completion_notification">Completion notification</h3>
<p>When the reviewer has completed the review item examination, R4E is used to send a completion notification via email. </p>
<h3 id="Examine_and_fix.2Freject_anomalies_2">Examine and fix/reject anomalies</h3>
<p>The author relies on the completion notification information to complete the anomaly examination. As a result, anomalies can either be accepted or rejected. Accepted anomalies can then be fixed. </p>
<h3 id="Mark_review_completed">Mark review completed</h3>
<p>When all anomalies have been fixed, the author can specify the exit decision and mark the review as completed. </p>
<h2 id="Formal_Review_workflow">Formal Review workflow</h2>
<p>R4E uses the IEEE Standard for Software Reviews (IEEE Std 1028-1997) for formal reviews. The process is broken down into four phases. </p>
<p>This process can be adapted to your organization. It is possible to use R4E to perform large reviews with several participants and formal meetings. It is also possible to use R4E for smaller one-on-one reviews with no formal meetings. </p>
<h3 id="Planning_Phase">Planning Phase</h3>
<p>
<img border="0" src="FormalReviewPlanning.png"/>
</p>
<p>During the Planning phase, the review organizer, lead and author(s) define the scope of the review. Together, they specify the list of review items. The review lead also takes care of the overall review scope and planning by specifying aspects like the participants, their roles, the review schedule, etc... </p>
<p>
<br/>
</p>
<h3 id="Preparation_Phase">Preparation Phase</h3>
<p>
<img border="0" src="FormalReviewPreparation.png"/>
</p>
<p>
<br/>
</p>
<p>During the Preparation phase, reviewers individually examine review items and record detected anomalies. This activity needs to be performed as preparation for the Decision phase. </p>
<p>
<br/>
</p>
<h3 id="Decision_Phase">Decision Phase</h3>
<p>
<img border="0" src="FormalReviewDecision.png"/>
</p>
<p>
<br/>
</p>
<p>During the Decision phase, review participants meet and analyze all submitted anomalies. Together they agree on which anomalies should be accepted and fixed in this particular phase of the project. Anomalies can be rejected because they are invalid or duplicated. They can also be postponed to another project. All accepted anomalies are assigned to the relevant authors for the Rework phase. </p>
<p>
<br/>
</p>
<h3 id="Rework_Phase">Rework Phase</h3>
<p>
<img border="0" src="FormalReviewRework.png"/>
</p>
<p>
<br/>
</p>
<p>During the Rework phase, authors fix all accepted anomalies assigned to them during the Decision phase. </p>
<p>
<br/>
</p>
<h2 id="Author">Author</h2>
<p>An Author is an R4E Participant that wrote the code being reviewed. Typically, authors are involved in fixing raised Anomalies. </p>
<h2 id="Anomaly">Anomaly</h2>
<p>An Anomaly is any condition that deviates from expectations based on requirements specifications, design documents, user documents, standards, etc., or from someone's perceptions of experiences. R4E Anomalies are typically created by reviewers during the review. They can also be found during test, analysis, compilation, or by users of software products or applicable documentation. </p>
<h2 id="Comment">Comment</h2>
<p>In the context of R4E, Comments are user commentaries that are associated to Anomalies as follow-up, or to provide complementary information. </p>
<h2 id="Commit_Review_Item">Commit Review Item</h2>
<p>A Commit Review Item is a review item that represents the file versions included together in a commit to a Version-Controlled Repository. A commit review item includes the ancestor version (base) and committed version (target) of the files. Commit Review Items are added to a review by Using the
<i>R4E Find Review Items</i> command on an Eclipse project.
</p>
<h2 id="Delta">Delta</h2>
<p>A Delta represents a single difference in a File Context between the base and target versions. A Delta can refer to content that was modified, added or removed within the file and can span one or multiple lines. </p>
<h2 id="File_Context">File Context</h2>
<p>A File Context represents a File included in the review. A file context includes references to the base (ancestor) and target (current) versions of the affected file. </p>
<h2 id="Global_Anomaly">Global Anomaly</h2>
<p>In the context of R4E, Global Anomalies are Anomalies that do not tie to a specific file or part of a file, but are rather applicable to the whole review or are general comments. </p>
<h2 id="Lead">Lead</h2>
<p>A Lead is an R4E Participant that is responsible to monitor the progress of the review and coordinate the work of the various participants. It should also be the person that has the final say on the closure of the review. </p>
<h2 id="Organizer">Organizer</h2>
<p>An Organizer is an R4E Participant that create the review and puts together the Review contents. Most of the time, the lead and the organizer are the same person. </p>
<h2 id="Participant">Participant</h2>
<p>A Participant is a user that is part at any given point of a review. A Participant can have one or more roles within the review. Possible roles includes Author, Lead, Organizer, or Reviewer </p>
<h2 id="Participants_List">Participants List</h2>
<p>A Participant List is a collection of multiple potential users, with their IDs and emails, which can be grouped together and added as a unit to a review.</p>
<h2 id="Postponed_Anomaly">Postponed Anomaly</h2>
<p>A Postponed Anomaly is an Anomaly that has been written in a previous review and that was set to state POSTPONED (i.e. it was not fixed/addressed then). Postponed anomalies can be imported in subsequent reviews to be addressed.</p>
<h2 id="Resource_Review_Item">Resource Review Item</h2>
<p>A Resource Review Item is a review item that represents a single Eclipse resource (typically a File). Resource Review Items are added to a review by manually selecting the affected file in the workspace </p>
<h2 id="Reviewer">Reviewer</h2>
<p>A Reviewer is an R4E Participant that reviews the code under review. Typically, reviewers are involved in raising Anomalies and following up on their resolution. </p>
<h2 id="Review_Group">Review Group</h2>
<p>A Review Group is a set of Reviews bundled together under the same directory and that have common factor(s) as determined by the user (e.g. Same Project, Product, Design Team, Organization, Time Span, etc.) </p>
<h2 id="Review">Review</h2>
<p>A Review is a collection of Review Items that are to be reviewed together, by the same reviewers, within a given time period. </p>
<h2 id="Review_Item">Review Item</h2>
<p>A Review Item is a collection of file contexts that will be reviewed as part of the current review. There are two types of Review Items currently supported: Commit Review Items and Resource Review Items. </p>
<h2 id="Rule">Rule</h2>
<p>A Rule represents a Design Rule that is to be enforced in the code. Design Rules should be enforced by the reviewers at review time. When a Rule is used in creating an anomaly, its values become the default values for the anomaly. </p>
<h2 id="Rule_Set">Rule Set</h2>
<p>A Rule Set is a collection of Design Rules that are bundled together as a unit. Rule Sets are associated to the Review Group in which they can be used </p>
<h2 id="Rule_Area">Rule Area</h2>
<p>A Rule Area is a container for Design Rules related to the same area. E.g. Java, C++, Testing etc. </p>
<h2 id="Rule_Violation">Rule Violation</h2>
<p>A Rule Violation is a Container for the multiple design rules associated to a category. E.g. Format, Performance, Syntax, etc. </p>
<h2 id="Selection">Selection</h2>
<p>A Selection represents the part of a File that was manually added to a review. A Selection can span one or multiple lines within a file, or could refer to the whole file itself. </p>
<p>
<br/>
</p><hr/>
<table class="navigation" style="width: 100%;" border="0" summary="navigation">
<tr>
<td style="width: 20%" align="left">
<a href="_r4eOpenUser.html" title="Getting Started">
<img alt="Previous" border="0" src="images/prev.gif"/>
</a>
</td>
<td style="width: 60%" align="center">
<a href="_r4eOpenUser.html" title="R4E Documentation">
<img alt="R4E Documentation" border="0" src="images/home.gif"/>
</a>
</td>
<td style="width: 20%" align="right">
<a href="Tasks.html" title="Tasks">
<img alt="Next" border="0" src="images/next.gif"/>
</a>
</td>
</tr>
<tr>
<td style="width: 20%" align="left" valign="top">Getting Started</td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right" valign="top">Tasks</td>
</tr>
</table>
</body>
</html>