Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Reviews/R4E/User Guide"
Line 1: | Line 1: | ||
− | = Getting Started = | + | = Getting Started = |
== Overview == | == Overview == | ||
− | |||
− | R4E aims to support multiple | + | Review for Eclipse (R4E) is a set of Eclipse plugins that provide eclipse-integrated code and text review functionality. R4E supports reviewing files associated to Eclipse projects and optionally included under a Version Control System. Three review workflows are included (Basic, Informal and IEEE standard 28-compatible Formal reviews). |
− | == | + | |
− | + | The main purpose of R4E is to review Source Code, especially Java and C/C++ Source code. Eventually, support for reviewing Data Models (based on EMF) will be included. R4E also aims to support multiple Version Control Systems (via Eclipse Team Providers). Git (implemented in Eclipse through EGit/JGit) is the only one supported in the initial version. | |
− | + | ||
− | == R4E Configuration == | + | The R4E User Interface includes three main components: '''R4E Review Navigator View''', '''R4E Properties View''' and '''R4E Context Menus''' |
− | R4E | + | |
− | ===Creating a Review Group=== | + | <br> [[Image:R4E main.png]] |
+ | |||
+ | |||
+ | |||
+ | The R4E Review Navigator View is the main interface to R4E. It shows all the R4E elements in a hierarchical tree structure The R4E Properties view presents the properties and attributes attached to each R4E element represented in the Review Navigator view. Some elements values can be altered after creation, and some other or read-only and settable at creation time. The R4E Context Menu appears in Eclipse Context menus whenever it is possible to use R4E command is this particular context. Please refer to [section] below for more information | ||
+ | |||
+ | <br> | ||
+ | |||
+ | == Starting R4E == | ||
+ | |||
+ | The start up R4E, show the Review Navigator View using the Eclipse Show View menu: | ||
+ | |||
+ | [[Image:R4E show view.png]] | ||
+ | |||
+ | <br> | ||
+ | |||
+ | == R4E Configuration == | ||
+ | |||
+ | The R4E Configuration can be entered by accessing the R4E Preferences Pages, which are part of the Eclipse Global Preferences. There are three R4E Preference Pages: '''R4E General Preferences''', '''R4E LDAP Settings''', and '''SMTP Hosts Definitions'''. | ||
+ | |||
+ | === R4E General Preferences === | ||
+ | |||
+ | R4E General Preferences page is split up into 4 tab sections. | ||
+ | |||
+ | <br> | ||
+ | |||
+ | *User Tab | ||
+ | |||
+ | [[Image:R4E preferences general user.png]] | ||
+ | |||
+ | |||
+ | |||
+ | This is used to enter the current user details. The User ID is set by default to the login ID of the current session and can be modified to any String that can be used to identify the user. The User Email should be set to a valid email for the user. The E-mail address is used to notify the user information about reviews he is currently part of by Email, as configured in the [[R4E/User Guide/SMTP Hosts Definitions]] Section. Take note that if the LDAP Preferences are filled-in (see below)and a corresponding LDAP database can be resolved, then this field will be automatically be set based on the User ID entered. | ||
+ | |||
+ | <br> | ||
+ | |||
+ | *'''Groups Tab''' | ||
+ | |||
+ | [[Image:R4E preferences general groups.png]] | ||
+ | |||
+ | |||
+ | |||
+ | This is used to specify the location of the data files that contain Review Group information. See below [link] for more information on Review Group. The Name and Description fields show additional information attached to the selected Review Group file. Typically, all R4E data files will be located on a shared network drive. Users can add one or multiple files to their Workspace as needed using the Add Button. Files can be removed from the Workspace by pressing the Remove Button. Files can be moved up or down in the list by clicking the corresponding button. This will affect the order in which the Groups are displayed in the Review Navigator [link] | ||
+ | |||
+ | <br> | ||
+ | |||
+ | *'''Rule Sets Tab''' | ||
+ | |||
+ | [[Image:R4E preferences general ruleSets.png]] | ||
+ | |||
+ | |||
+ | |||
+ | This is used to specify the location of the data files that contain Rule Set information. See below [link] for more information on Rule Sets. The Name and Version fields show additional information attached to the selected Rule Set file. Typically, all R4E data files will be located on a shared network drive. Users can add one or multiple files to their Workspace as needed using the Add Button. Files can be removed from the Workspace by pressing the Remove Button. Files can be moved up or down in the list by clicking the corresponding button. This will affect the order in which the Rule Sets are displayed in the Review Navigator [link] | ||
+ | |||
+ | <br> | ||
+ | |||
+ | *'''Filter Tabs''' | ||
+ | |||
+ | [[Image:R4E preferences general filters.png]] | ||
+ | |||
+ | |||
+ | |||
+ | This is used to set-up default filters that will be applied to the Review Navigator view. See the Filter section below [link] for the various filters description | ||
+ | |||
+ | <br> | ||
+ | |||
+ | === R4E LDAP Settings === | ||
+ | |||
+ | [[Image:R4E preferences ldap.png]] | ||
+ | |||
+ | This is used the specify configuration for an available LDAP database server that contains information about the users. The Server Information part contains LDAP server information (Host, Port, DN (Distinguished Name), and Login User Name and Password) to use. The Mandatory Parameters part contains mapping values for LDAP attributes that maps the User Id, Name and E-Mail parameters The Optional Parameters part contains mapping values for LDAP attributes that maps optional parameters that could exists in the database. | ||
+ | |||
+ | This is optional. If no information is entered, LDAP funxtionality will be unavailable, but will not affect R4E otherwise | ||
+ | |||
+ | <br> | ||
+ | |||
+ | === SMTP Hosts Definitions === | ||
+ | |||
+ | [[Image:R4E preferences smtp.png]] | ||
+ | |||
+ | This is used to specify the mail server(s) that will be used to send manual and automatic email notifications to the users. More than one server can be specified. Users can add one or multiple servers to their Workspace as needed using the Add Button. Servers can be removed from the Workspace by pressing the Remove Button. Servers can be moved up or down in the list by clicking the corresponding button. The primary server should always be the first on the list. | ||
+ | |||
+ | <br> | ||
+ | |||
+ | === Creating a Review Group === | ||
+ | |||
You will first need to create a Review Group to associate your reviews. | You will first need to create a Review Group to associate your reviews. | ||
− | * Open the R4E Navigator View '''Window > Show View > R4E > Review Navigator''' | + | |
− | [[Image:ReviewNavigatorEmpty.jpg]] | + | *Open the R4E Navigator View '''Window > Show View > R4E > Review Navigator''' |
− | * Click the icon "Add a new Review Group" | + | |
− | * Select a shared folder location where team members have access and write permissions (i.e. Review Group shared folder) | + | [[Image:ReviewNavigatorEmpty.jpg]] |
− | [[Image:NewGroupDialog.jpg]] | + | |
− | ===Opening an Existing Review Group=== | + | *Click the icon "Add a new Review Group" |
− | * If a Review Group is already created, you need to define its shared location in your workspace preferences. | + | *Select a shared folder location where team members have access and write permissions (i.e. Review Group shared folder) |
− | * Select the Review file ending with "_group_root.xrer" | + | |
− | [[Image: | + | [[Image:NewGroupDialog.jpg]] |
− | == Eclipse Project Configuration == | + | |
− | *R4E can only operate with projects associated with Egit as team provider, The [http://wiki.eclipse.org/EGit/User_Guide "EGit/User Guide"] is the best place to find the information on how to create new git repositories, work with existing git repositories and importing Eclipse projects under and existing git repository into the Eclipse workspace. | + | === Opening an Existing Review Group === |
− | [http://wiki.eclipse.org/EGit/User_Guide "EGit/User Guide"] | + | |
+ | *If a Review Group is already created, you need to define its shared location in your workspace preferences. '''Preferences > R4E''' | ||
+ | *Select the Review file ending with "_group_root.xrer" | ||
+ | |||
+ | [[Image:R4e preferences.jpg]] | ||
+ | |||
+ | == Eclipse Project Configuration == | ||
+ | |||
+ | *R4E can only operate with projects associated with Egit as team provider, The [http://wiki.eclipse.org/EGit/User_Guide "EGit/User Guide"] is the best place to find the information on how to create new git repositories, work with existing git repositories and importing Eclipse projects under and existing git repository into the Eclipse workspace. | ||
+ | |||
+ | [http://wiki.eclipse.org/EGit/User_Guide "EGit/User Guide"] | ||
+ | |||
*Once the project is associated/connected to the Egit team provider the project will display the project name and associated branch between brackets. | *Once the project is associated/connected to the Egit team provider the project will display the project name and associated branch between brackets. | ||
− | [[Image: | + | |
− | = Concepts = | + | [[Image:ProjectWithTeamProvider.jpg]] |
− | == Review Group == | + | |
− | A set of Reviews bundled together under the same directory and have a common factor determined by the user e.g. common Project, Product, Time Span, etc.. | + | = Concepts = |
− | == Review == | + | |
+ | == Review Group == | ||
+ | |||
+ | A set of Reviews bundled together under the same directory and have a common factor determined by the user e.g. common Project, Product, Time Span, etc.. | ||
+ | |||
+ | == Review == | ||
+ | |||
*Entity which holds information and references to the Items under review, the participants, the findings (anomalies), status, etc.. | *Entity which holds information and references to the Items under review, the participants, the findings (anomalies), status, etc.. | ||
− | == Review Item == | + | |
+ | == Review Item == | ||
+ | |||
*There are three types of Review Items to be supported | *There are three types of Review Items to be supported | ||
− | ===Commit=== | + | |
+ | === Commit === | ||
+ | |||
*A commit to a version control system repository, representing the affected files (before and after modifications) also called base and target. | *A commit to a version control system repository, representing the affected files (before and after modifications) also called base and target. | ||
− | In this type of Review Item the base and target files are part of a commit in the version control system. | + | |
− | ===Resource=== | + | In this type of Review Item the base and target files are part of a commit in the version control system. |
+ | |||
+ | === Resource === | ||
+ | |||
*This represents review items created by manually selecting a portion of the file (Resource) as the target for review. | *This represents review items created by manually selecting a portion of the file (Resource) as the target for review. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | = Tasks = | + | === Patch === |
− | ==Creating a Review== | + | |
− | From the Review Navigator view, right click to open up the context menu | + | '''Not supported just yet''' Will hold the references to the affected files plus a delta change, these type of review items will require the base file to be part of a commit within the version control system whereas the updated file many not have been committed to the version control system. |
− | [[Image: | + | |
− | [[Image:NewReviewDialog.jpg]] | + | == Review Anomaly == |
− | ==Creating a Review Item== | + | |
− | There are two types of Review Items to add to an R4E Review | + | Any condition that deviates from expectations based on requirements specifications, design documents, user documents, standards, etc., or from someone's perceptions of experiences. Anomalies may be found during, but not limited to, the review, test, analysis, compilation, or use of software products or applicable documentation. |
− | ===Creating a Resource Review Item=== | + | |
− | These types of items are created from the manual selection of a Workspace resource (i.e. File) or a portion of a resource (line ranges within a file). | + | = Tasks = |
− | *To create Resource review items for a whole file, right click a File on a Package Explorer, Navigator or Project View to see the menu in the following picture. | + | |
− | *To create Resource review items for a portion of a file, right click a line range selection on an editor or compare editor (spawned from R4E Navigator) to see the context menu in the following picture. | + | == Creating a Review == |
− | [[Image:R4EAddContextMenu.jpg]] | + | |
− | ===Creating a Commit Review Item=== | + | From the Review Navigator view, right click to open up the context menu [[Image:AddReviewMenu.jpg]] [[Image:NewReviewDialog.jpg]] |
− | To create a commit review item, right click on a project attached to the Egit team provider (see Project Configuration) to access the context menu shown below. | + | |
+ | == Creating a Review Item == | ||
+ | |||
+ | There are two types of Review Items to add to an R4E Review | ||
+ | |||
+ | === Creating a Resource Review Item === | ||
+ | |||
+ | These types of items are created from the manual selection of a Workspace resource (i.e. File) or a portion of a resource (line ranges within a file). | ||
+ | |||
+ | *To create Resource review items for a whole file, right click a File on a Package Explorer, Navigator or Project View to see the menu in the following picture. | ||
+ | *To create Resource review items for a portion of a file, right click a line range selection on an editor or compare editor (spawned from R4E Navigator) to see the context menu in the following picture. | ||
+ | |||
+ | [[Image:R4EAddContextMenu.jpg]] | ||
+ | |||
+ | === Creating a Commit Review Item === | ||
+ | |||
+ | To create a commit review item, right click on a project attached to the Egit team provider (see Project Configuration) to access the context menu shown below. | ||
+ | |||
+ | [[Image:FindReviewItemsMenu.jpg]] | ||
+ | |||
+ | The Last commit is proposed as the review item. [[Image:FindReviewItemsDialog.jpg]] | ||
+ | |||
+ | == Creating an Anomaly == | ||
+ | |||
+ | Similarly to Resource Review Items an anomaly can be created from a selected Resource or a portion of a resource. [[Image:R4EAddContextMenu.jpg]] | ||
+ | |||
+ | [[Image:AddAnomaliesCompareEditor.jpg]] | ||
+ | |||
+ | [[Image:NewAnomalyDialog.jpg]] | ||
− | + | == Creating a Global Anomaly == | |
− | + | Global anomalies are not specific to a Resource and the scope shall be described by the creator, the context menu for it is under the '''R4E Navigator -> Global Anomalies''' | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | [[Image: | + | [[Image:AddGlobalAnomaly.jpg]] |
− | + | == Adding Comments to an existing Anomaly == | |
− | + | It is possible to establish a dialog related to a specific selected anomaly. So each user can add his/hers specific comments. | |
− | + | ||
− | [[Image: | + | [[Image:NewCommentMenu.jpg]] |
− | + | [[Image:NewCommentDialog.jpg]] | |
− | + | ||
− | + | == Updating Review Elements == | |
− | + | Updates to any review elements are performed via the Eclipse properties view, by modifying the context of the corresponding text box. | |
− | + | [[Image:ReviewProperties.jpg]] | |
− | + | ||
− | + | == Using Filters in the Navigator View == | |
− | |||
The Navigator view provides different kind of filters to limit the visible items within the tree of review elements | The Navigator view provides different kind of filters to limit the visible items within the tree of review elements |
Revision as of 16:16, 30 May 2011
Contents
Getting Started
Overview
Review for Eclipse (R4E) is a set of Eclipse plugins that provide eclipse-integrated code and text review functionality. R4E supports reviewing files associated to Eclipse projects and optionally included under a Version Control System. Three review workflows are included (Basic, Informal and IEEE standard 28-compatible Formal reviews).
The main purpose of R4E is to review Source Code, especially Java and C/C++ Source code. Eventually, support for reviewing Data Models (based on EMF) will be included. R4E also aims to support multiple Version Control Systems (via Eclipse Team Providers). Git (implemented in Eclipse through EGit/JGit) is the only one supported in the initial version.
The R4E User Interface includes three main components: R4E Review Navigator View, R4E Properties View and R4E Context Menus
The R4E Review Navigator View is the main interface to R4E. It shows all the R4E elements in a hierarchical tree structure The R4E Properties view presents the properties and attributes attached to each R4E element represented in the Review Navigator view. Some elements values can be altered after creation, and some other or read-only and settable at creation time. The R4E Context Menu appears in Eclipse Context menus whenever it is possible to use R4E command is this particular context. Please refer to [section] below for more information
Starting R4E
The start up R4E, show the Review Navigator View using the Eclipse Show View menu:
R4E Configuration
The R4E Configuration can be entered by accessing the R4E Preferences Pages, which are part of the Eclipse Global Preferences. There are three R4E Preference Pages: R4E General Preferences, R4E LDAP Settings, and SMTP Hosts Definitions.
R4E General Preferences
R4E General Preferences page is split up into 4 tab sections.
- User Tab
This is used to enter the current user details. The User ID is set by default to the login ID of the current session and can be modified to any String that can be used to identify the user. The User Email should be set to a valid email for the user. The E-mail address is used to notify the user information about reviews he is currently part of by Email, as configured in the R4E/User Guide/SMTP Hosts Definitions Section. Take note that if the LDAP Preferences are filled-in (see below)and a corresponding LDAP database can be resolved, then this field will be automatically be set based on the User ID entered.
- Groups Tab
This is used to specify the location of the data files that contain Review Group information. See below [link] for more information on Review Group. The Name and Description fields show additional information attached to the selected Review Group file. Typically, all R4E data files will be located on a shared network drive. Users can add one or multiple files to their Workspace as needed using the Add Button. Files can be removed from the Workspace by pressing the Remove Button. Files can be moved up or down in the list by clicking the corresponding button. This will affect the order in which the Groups are displayed in the Review Navigator [link]
- Rule Sets Tab
This is used to specify the location of the data files that contain Rule Set information. See below [link] for more information on Rule Sets. The Name and Version fields show additional information attached to the selected Rule Set file. Typically, all R4E data files will be located on a shared network drive. Users can add one or multiple files to their Workspace as needed using the Add Button. Files can be removed from the Workspace by pressing the Remove Button. Files can be moved up or down in the list by clicking the corresponding button. This will affect the order in which the Rule Sets are displayed in the Review Navigator [link]
- Filter Tabs
This is used to set-up default filters that will be applied to the Review Navigator view. See the Filter section below [link] for the various filters description
R4E LDAP Settings
This is used the specify configuration for an available LDAP database server that contains information about the users. The Server Information part contains LDAP server information (Host, Port, DN (Distinguished Name), and Login User Name and Password) to use. The Mandatory Parameters part contains mapping values for LDAP attributes that maps the User Id, Name and E-Mail parameters The Optional Parameters part contains mapping values for LDAP attributes that maps optional parameters that could exists in the database.
This is optional. If no information is entered, LDAP funxtionality will be unavailable, but will not affect R4E otherwise
SMTP Hosts Definitions
This is used to specify the mail server(s) that will be used to send manual and automatic email notifications to the users. More than one server can be specified. Users can add one or multiple servers to their Workspace as needed using the Add Button. Servers can be removed from the Workspace by pressing the Remove Button. Servers can be moved up or down in the list by clicking the corresponding button. The primary server should always be the first on the list.
Creating a Review Group
You will first need to create a Review Group to associate your reviews.
- Open the R4E Navigator View Window > Show View > R4E > Review Navigator
- Click the icon "Add a new Review Group"
- Select a shared folder location where team members have access and write permissions (i.e. Review Group shared folder)
Opening an Existing Review Group
- If a Review Group is already created, you need to define its shared location in your workspace preferences. Preferences > R4E
- Select the Review file ending with "_group_root.xrer"
Eclipse Project Configuration
- R4E can only operate with projects associated with Egit as team provider, The "EGit/User Guide" is the best place to find the information on how to create new git repositories, work with existing git repositories and importing Eclipse projects under and existing git repository into the Eclipse workspace.
- Once the project is associated/connected to the Egit team provider the project will display the project name and associated branch between brackets.
Concepts
Review Group
A set of Reviews bundled together under the same directory and have a common factor determined by the user e.g. common Project, Product, Time Span, etc..
Review
- Entity which holds information and references to the Items under review, the participants, the findings (anomalies), status, etc..
Review Item
- There are three types of Review Items to be supported
Commit
- A commit to a version control system repository, representing the affected files (before and after modifications) also called base and target.
In this type of Review Item the base and target files are part of a commit in the version control system.
Resource
- This represents review items created by manually selecting a portion of the file (Resource) as the target for review.
Patch
Not supported just yet Will hold the references to the affected files plus a delta change, these type of review items will require the base file to be part of a commit within the version control system whereas the updated file many not have been committed to the version control system.
Review Anomaly
Any condition that deviates from expectations based on requirements specifications, design documents, user documents, standards, etc., or from someone's perceptions of experiences. Anomalies may be found during, but not limited to, the review, test, analysis, compilation, or use of software products or applicable documentation.
Tasks
Creating a Review
From the Review Navigator view, right click to open up the context menu
Creating a Review Item
There are two types of Review Items to add to an R4E Review
Creating a Resource Review Item
These types of items are created from the manual selection of a Workspace resource (i.e. File) or a portion of a resource (line ranges within a file).
- To create Resource review items for a whole file, right click a File on a Package Explorer, Navigator or Project View to see the menu in the following picture.
- To create Resource review items for a portion of a file, right click a line range selection on an editor or compare editor (spawned from R4E Navigator) to see the context menu in the following picture.
Creating a Commit Review Item
To create a commit review item, right click on a project attached to the Egit team provider (see Project Configuration) to access the context menu shown below.
The Last commit is proposed as the review item.
Creating an Anomaly
Similarly to Resource Review Items an anomaly can be created from a selected Resource or a portion of a resource.
Creating a Global Anomaly
Global anomalies are not specific to a Resource and the scope shall be described by the creator, the context menu for it is under the R4E Navigator -> Global Anomalies
Adding Comments to an existing Anomaly
It is possible to establish a dialog related to a specific selected anomaly. So each user can add his/hers specific comments.
Updating Review Elements
Updates to any review elements are performed via the Eclipse properties view, by modifying the context of the corresponding text box.
The Navigator view provides different kind of filters to limit the visible items within the tree of review elements