Changes between Version 14 and Version 15 of PeerReviewPlugin/Documentation


Ignore:
Timestamp:
Feb 2, 2016, 6:13:59 PM (6 years ago)
Author:
figaro
Comment:

Cosmetic changes, emphasised images with border

Legend:

Unmodified
Added
Removed
Modified
  • PeerReviewPlugin/Documentation

    v14 v15  
    55== Overview
    66
    7 [PeerReviewPlugin Distributed Peer Review system] is a plugin for Trac that facilitates distributed peer review of code. Normally peer review happens in a central location with paper copies of code, or works in an disorganized fashion involving email or other electronic means to communicate. However, these systems are inefficient for multiple code reviews, and can become unmanageable very quickly. Hence, this system assists developers in managing and performing code reviews in a distributed way.
     7The PeerReviewPlugin is a plugin for Trac that facilitates distributed peer review of code. Normally peer review happens in a central location with paper copies of code, or works in an unstructured fashion involving email or other electronic means to communicate. However, these systems are inefficient for multiple code reviews, and can become unmanageable very quickly. Hence, this plugin assists developers in managing and performing code reviews in a distributed and centralised way.
    88
    99== Description
    1010
    11 Distributed peer review facilitates code review without the need for all team members to meet together, saving time. In addition, changes proposed under a distributed system are easier to implement. Our project seeks to create a distributed peer review system by creating a plugin for Trac, which is a browser-based content management system that includes bug-tracking. The plugin integrates with Subversion, a popular open-source version control system.
    12 
     11Distributed peer review facilitates code review without the need for all team members to meet at the same time, thereby saving time. In addition, changes proposed under a distributed system are easier to implement. This project aims to create a distributed peer review system by creating a plugin for Trac, which is a browser-based content management system that includes bug-tracking. The plugin integrates with Subversion, a popular open-source version control system.
    1312
    1413'''Note:''' Since version 2.1 this plugin uses the new template engine Genshi, and supports SQLite, PostgreSQL and MySQL as database backends.
     
    2221The first table is the list of code reviews where you are the author. Clicking on any element in a particular row will take you to the View Code Review page for that row. Also, this table displays the code review ID, code review name, current status of the review, and the date that the review was opened.
    2322
    24 [[Image(mainPage_2.PNG, 500px)]]
     23[[Image(mainPage_2.PNG, 500px, border=2)]]
    2524
    2625The second table is the list of code reviews where you are the reviewer. Clicking on any element in a particular row will redirect to the View Code Review page for that row. Also, this table displays the code review ID, code review author, review name, your voting status for the review, and the date that the review was opened.
    2726
    28 [[Image(mainPage_3.PNG, 500px)]]
     27[[Image(mainPage_3.PNG, 500px, border=2)]]
    2928
    3029Managers will see an additional table at the top of the page above the two tables that are typically there for a developer. These are the code reviews that need to be reviewed by a manager. After approval by a manager, the manager should add the changes in the code review to the development trunk.
    3130
    32 [[Image(mainPage_1.PNG, 500px)]]
     31[[Image(mainPage_1.PNG, 500px, border=2)]]
    3332
    3433Finally, just below the navigation bar in the upper right corner are some navigation links for moving through the plugin. The links will take you to the Main Page, New Code Review Page, and Search Code Review Page, respectively.
     
    4443
    4544==== Choose a name
    46 This will be the name that will appear on the main page after the code review is created. A name cannot be longer than fifty characters in length.
    47 
    48 [[Image(newCodeReview_step1.PNG, 300px)]]
     45
     46This will be the name that will appear on the main page after the code review is created. A name cannot be longer than 50 characters in length.
     47
     48[[Image(newCodeReview_step1.PNG, 300px, border=2)]]
    4949
    5050==== Add files
    51 The user is presented with the Subversion repository tied to TRAC.
    52 
    53 Navigation through this repository is identical to navigation through the TRAC repository.  Clicking on folders navigates through the folder.  Clicking on files will open that file if an HTML preview is available.  To navigate back up, click on the corresponding folder above the repository (for example, where it says "root").
    54 
    55 [[Image(newCodeReview_step2_1.PNG, 700px)]]
     51
     52The user is presented with the Subversion repository tied to Trac.
     53
     54Navigation through this repository is identical to navigation through the Trac repository. Clicking on folders navigates through the folder. Clicking on files will open that file if an HTML preview is available. To navigate back up, click on the corresponding folder above the repository, for example, where it says "root".
     55
     56[[Image(newCodeReview_step2_1.PNG, 700px, border=2)]]
    5657
    5758Once a file has been opened, the repository browser will look similar to this:
    5859
    59 [[Image(newCodeReview_step2_2.PNG, 700px)]]
     60[[Image(newCodeReview_step2_2.PNG, 700px, border=2)]]
    6061
    6162There are two ways to select a file to be added into the peer review.
    6263 1. Select one or more files in the repository browser and click ''Add files''. This adds the complete files to a review. Note that the select boxes are not shown in the screenshots.
    63  1. Click the corresponding lines of code on the left that you would like to add.  For example, here the user clicked on 82 and clicked on 87 to select lines 82-87. Alternately, the user could type those numbers into the corresponding text boxes below the repository browser.
     64 1. Click the corresponding lines of code on the left that you would like to add. For example, here the user clicked on 82 and clicked on 87 to select lines 82-87. Alternatively, the user could type those numbers into the corresponding text boxes below the repository browser.
    6465 
    6566 Once the correct lines of code have been selected, click ''Add File'' to add the code to the code review. The location will appear in the table below the repository browser, along with the line numbers and revision number.
    6667
    67 
    6868==== Add reviewers
    69 Select reviewers from the dropdown list and click "Add user" to add them to the table of reviewers.  This is the list of people that will vote on whether or not the code for the current code review is acceptable.  Reviewers may be removed by clicking their names in the reviewers table.
    70 
    71 Only users with permission ''CODE_REVIEW_DEV'' will be shown in the dropdown list.
    72 
    73 [[Image(newCodeReview_step3.PNG, 250px)]]
     69
     70Select reviewers from the dropdown list and click "Add user" to add them to the table of reviewers. This is the list of people that will vote on whether or not the code for the current code review is acceptable. Reviewers may be removed by clicking their names in the reviewers table.
     71
     72Only users with permission `CODE_REVIEW_DEV` will be shown in the dropdown list.
     73
     74[[Image(newCodeReview_step3.PNG, 250px, border=2)]]
    7475
    7576==== Provide notes and instructions
     
    7778General comments can be added to the code review. These comments can be seen by anyone viewing the code review.
    7879
    79 [[Image(newCodeReview_step4.PNG, 400px)]]
    80 
    81 After adding general comments, the user is ready to add the code review. Click "Add Code Review" at the bottom of the page to do this.  The user will be taken to the View Code Review page for this code review.
     80[[Image(newCodeReview_step4.PNG, 400px, border=2)]]
     81
     82After adding general comments, the user is ready to add the code review. Click "Add Code Review" at the bottom of the page to do this. The user will be taken to the View Code Review page for this code review.
    8283
    8384=== Peer Review Search
    84 This page helps search for code reviews, given relevant information to find the correct code reviews.  First, search constraints are selected, and then a search is performed by clicking on the search button.  When search constraints are selected and a search is performed, code reviews that still satisfy the constraints are listed.  If no constraints are given, all reviews, both active and inactive (closed), are listed.  Combinations of fields narrow the search results.  For example, searching for reviews after one month ago and by a certain author will likely return less results than searching by one of the constraints alone.  It is possible to constrain the search such that no results are returned.  Such a condition is indicated after searching.
    85 
    86 [[Image(peerReviewSearch_1.PNG, 700px)]]
    87 
    88 To find a particular code review name or code review names that contain certain characters, enter it in the "Code Review Name" field.  Further, to find reviews after a certain date, enter the date in the second set of input boxes.  Likewise, to constrain the returned results of the search to a certain status, change the "Status" field.  Finally, to find all code reviews matching a certain author, fill in the final field.  After specifying the constraints for the search, click on the "Search" button.
    89 
    90 [[Image(peerReviewSearch_2.PNG, 700px)]]
    91 
    92 As seen above, the results include information on the review ID, author name, current status, and review name.  For each review listed, links are given to jump directly to the view code review page for the review.  Alternately, the constraints can be increased or relaxed by choosing different values for the fields and searching again.
     85
     86This page helps search for code reviews, given relevant information to find the correct code reviews. First, search constraints are selected, and then a search is performed by clicking on the search button. When search constraints are selected and a search is performed, code reviews that still satisfy the constraints are listed. If no constraints are given, all reviews, both active and inactive (closed), are listed.
     87
     88Combinations of fields narrow the search results. For example, searching for reviews after one month ago and by a certain author will likely return less results than searching by one of the constraints alone. It is possible to constrain the search such that no results are returned. Such a condition is indicated after searching.
     89
     90[[Image(peerReviewSearch_1.PNG, 700px, border=2)]]
     91
     92To find a particular code review name or code review names that contain certain characters, enter it in the "Code Review Name" field. Further, to find reviews after a certain date, enter the date in the second set of input boxes. Likewise, to constrain the returned results of the search to a certain status, change the "Status" field. Finally, to find all code reviews matching a certain author, fill in the final field. After specifying the constraints for the search, click on the "Search" button.
     93
     94[[Image(peerReviewSearch_2.PNG, 700px, border=2)]]
     95
     96As seen above, the results include information on the review ID, author name, current status, and review name. For each review listed, links are given to jump directly to the view code review page for the review. Alternately, the constraints can be increased or relaxed by choosing different values for the fields and searching again.
     97
    9398=== Perform Code Review
    94 This page allows commentary on code reviews, and viewing others' comments.  All users can see the comments posted on this page.
    95 
    96 [[Image(performCodeReview_1.PNG, 700px)]]
     99
     100This page allows commentary on code reviews, and viewing others' comments. All users can see the comments posted on this page.
     101
     102[[Image(performCodeReview_1.PNG, 700px, border=2)]]
    97103
    98104The page shows the file that is being commented on, as well as the revision number and starting and ending lines. Initially, the page shows the section under review with three lines of code on either side of the section. To expand the number of buffer lines shown at the beginning and end of a section, edit:
    99105
    100 [[Image(performCodeReview_2.PNG, 300px)]]
    101 
    102 Note that the number of lines will never exceed the beginning or end of the document.  In the case that an invalid number of lines is provided, the page will restore the last valid value entered.
     106[[Image(performCodeReview_2.PNG, 300px, border=2)]]
     107
     108Note that the number of lines will never exceed the beginning or end of the document. In the case that an invalid number of lines is provided, the page will restore the last valid value entered.
    103109
    104110Comments can be associated with each line in the range of lines the author wants others to examine. If a line already has some comments, it is denoted with a 'pin' symbol. The line numbers are links that will open a comment editor:
    105111
    106 [[Image(performCodeReview_4.PNG, 400px)]]
     112[[Image(performCodeReview_4.PNG, 400px, border=2)]]
    107113
    108114After the comments box is opened, the "Refresh" link updates the comments box to the most updated comments (which is automatically done whenever the box is initially loaded). Also, users can reply directly to previous posts by clicking the "Reply" link under the existing comment.
     
    110116Alternately, users can add a new comment by clicking the "Add New Comment" button:
    111117
    112 [[Image(performCodeReview_5.PNG, 300px)]]
    113 
    114 This will open up a new comment box, as shown above, where comments can be inserted into the text box.  A code sample can be attached as well by clicking on the "Attach Code Sample" box.  Then, type the pathname to the desired file on your computer or click the "Browse..." button to pull up a file selection dialog which will fill in the filename. Finally, click on the "Add Comment" button to add the comment so others can view it, or click on the 'X' in the upper-right hand corner to cancel at any time.
     118[[Image(performCodeReview_5.PNG, 300px, border=2)]]
     119
     120This will open up a new comment box, as shown above, where comments can be inserted into the text box. A code sample can be attached as well by clicking on the "Attach Code Sample" box. Then, type the pathname to the desired file on your computer or click the "Browse..." button to pull up a file selection dialog which will populate the filename. Finally, click on the "Add Comment" button to add the comment so others can view it, or click on the 'X' in the upper-right hand corner to cancel at any time.
    115121
    116122=== View Code Review
     
    120126At the top of the page the name, status, author, and creation date of the code review are listed:
    121127
    122 [[Image(viewCodeReview_1.PNG, 500px)]]
     128[[Image(viewCodeReview_1.PNG, 500px, border=2)]]
    123129
    124130Next, the files that this code review encompasses are listed:
    125131
    126 [[Image(viewCodeReview_2.PNG, 700px)]]
    127 
    128 The file ID, filename, revision number, and line numbers of the files are prominently displayed in this table. Upon clicking on any of the links given in the table, the user will be taken to the perform code review page for the file in question. Note that this file is unique for each code review, regardless of duplication across separate code reviews. Also, the filename can be identical, with different line numbers.  This is so that two very different portions of the file that the author modified can be shown without all of the lines in between. In the example above, about 140 lines would have needed to be shown if only one file was used.
     132[[Image(viewCodeReview_2.PNG, 700px, border=2)]]
     133
     134The file ID, filename, revision number, and line numbers of the files are prominently displayed in this table. Upon clicking on any of the links given in the table, the user will be taken to the perform code review page for the file in question. Note that this file is unique for each code review, regardless of duplication across separate code reviews. Also, the filename can be identical, with different line numbers. This is so that two different portions of the file that the author modified can be shown without all of the lines in between. In the example above, about 140 lines would have been needed to be shown if only one file was used.
    129135
    130136Next, the users assigned to this code review and their vote status are visible.
     
    132138Managers can see whether each user has voted, and what their vote was if they have voted:
    133139
    134 [[Image(viewCodeReview_4.PNG, 700px)]]
     140[[Image(viewCodeReview_4.PNG, 700px, border=2)]]
    135141
    136142The author of the review can only see whether each user has voted or not:
    137143
    138 [[Image(viewCodeReview_9.PNG, 700px)]]
     144[[Image(viewCodeReview_9.PNG, 700px, border=2)]]
    139145
    140146Users that are neither author nor manager of the review can only see the users that are assigned to the code review:
    141147
    142 [[Image(viewCodeReview_3.PNG, 700px)]]
    143 
    144 Next, the author's notes and instructions are visible, which are general comments that the author has about the code review:
    145 
    146 [[Image(viewCodeReview_5.PNG, 350px)]]
     148[[Image(viewCodeReview_3.PNG, 700px, border=2)]]
     149
     150Next, the author's notes and instructions are visible, which are general comments that the author added about the code review:
     151
     152[[Image(viewCodeReview_5.PNG, 350px, border=2)]]
    147153
    148154Below this is the vote summary, which summarizes the votes for insertion into the main trunk of the project, votes against insertion into the main trunk of the project, and votes that have not been cast:
    149155
    150 [[Image(viewCodeReview_6.PNG, 350px)]]
     156[[Image(viewCodeReview_6.PNG, 350px, border=2)]]
    151157
    152158This summary is only visible if the user is a manager or author or is a reviewer that has voted.
     
    154160Voting members for the code review can vote if they have not voted, or view their votes and modify them if they have voted:
    155161
    156 [[Image(viewCodeReview_7.PNG, 300px)]]
     162[[Image(viewCodeReview_7.PNG, 300px, border=2)]]
    157163
    158164The author of the review can submit the code review for inclusion, resubmit for review, or close the code review:
    159165
    160 [[Image(viewCodeReview_10.PNG, 350px)]]
     166[[Image(viewCodeReview_10.PNG, 350px, border=2)]]
    161167
    162168Submitting the review for inclusion can only be performed when the percentage of the reviewers that have voted 'Yes' exceeds the threshold set by the manager.
    163169
    164 There is no way to change a code review once it has been created.  However, resubmitting for review closes a code review and creates a new code review with the same parameters.  A developer might want to resubmit for review if changes were proposed and the changes have been implemented.  In this case, there is a different set of code for reviewers to look at, so a new review should be created to reflect this. However, creating another review with the same parameters would normally be painstaking.
    165 
    166 Authors can also close their code reviews, removing it from reviewers' main pages.  It can still be viewed when searching.
     170There is no way to change a code review once it has been created. However, resubmitting for review closes a code review and creates a new code review with the same parameters. A developer might want to resubmit for review if changes were proposed and the changes have been implemented. In this case, there is a different set of code for reviewers to look at, so a new review should be created to reflect this. However, creating another review with the same parameters would normally be painstaking.
     171
     172Authors can also close their code reviews, removing it from reviewers' main pages. It can still be viewed when searching.
    167173
    168174Finally, if you are the manager of a code review, you can change the status or resubmit for review at any time:
    169175
    170 [[Image(viewCodeReview_8.PNG, 350px)]]
     176[[Image(viewCodeReview_8.PNG, 350px, border=2)]]
    171177
    172178=== Manager Options
     179
    173180This page allows a manager to set manager options.
    174181
    175 [[Image(options_1.PNG, 700px)]]
     182[[Image(options_1.PNG, 700px, border=2)]]
    176183
    177184The voting threshold is currently the only manager option that can be set. The voting threshold can be changed by altering the value in the field to an integer value between 0 and 100 and clicking on the "Set Threshold" button.
     
    179186== Glossary
    180187
    181 Some terms that are exclusive to the peer review plug-in (as opposed to being in TRAC or Subversion) are defined here.
    182 
    183  Author:: The user that created a code review.  Has special privileges, which are overridden if the user is also a manager.
     188Some terms that are exclusive to the peer review plugin (as opposed to being in Trac or Subversion) are defined here.
     189
     190 Author:: The user that created a code review. Has special privileges, which are overridden if the user is also a manager.
    184191
    185192 Code review:: A collection of reviewers and a collection of files to be reviewed.
    186193
    187  Developer:: A normal user.  Can create code reviews and be assigned as a reviewer to them. Can search for code reviews, see reviews they created, and see reviews they are assigned to.
    188 
    189  Manager:: User with highest privileges.  Can do everything that a developer can do.  Can also change the status of a review at any time.  When reviews have "Ready for inclusion" status, these appear on the manager's main page in a table. Can also view the Manager Options page.
    190 
    191  Resubmit:: Resubmitting for review takes an existing code review and creates a new code review based on it.  The fields of the new review are filled in as they were when the original code review was created, and then the author can edit the review details. After creating this new review, the old one is closed.
     194 Developer:: A normal user. Can create code reviews and be assigned as a reviewer to them. Can search for code reviews, see reviews they created, and see reviews they are assigned to.
     195
     196 Manager:: User with highest privileges. Can do everything that a developer can do. Can also change the status of a review at any time. When reviews have "Ready for inclusion" status, these appear on the manager's main page in a table. Can also view the Manager Options page.
     197
     198 Resubmit:: Resubmitting for review takes an existing code review and creates a new code review based on it. The fields of the new review are filled in as they were when the original code review was created, and then the author can edit the review details. After creating this new review, the old one is closed.
    192199
    193200 Reviewer:: A developer or manager that is assigned to review a code review, make comments, and vote on the review.
    194201
    195  Status:: The current state of the code review.  The status dictates whether or not certain actions are possible.  A manager can change the state at any time, and the author can close the review when it is open or reviewed. States include:
    196 
    197    * ''Open for review'' - Initial state of the review, where reviewers can vote on the review and add comments.
    198    * ''Reviewed'' - Enough people have voted yes to push the review over the threshold limit. At this point the review can be submitted for inclusion by the author.
    199    * ''Ready for inclusion'' - The author feels, and his/her reviewers agree, that the review is ready for inclusion into the main trunk.  At this point it is the manager's responsibility to verify the review, merge the changes with the main trunk, and close the review when finished. No voting is possible during this stage.
    200    * ''Closed'' - The review can be viewed, but no more voting is possible.  The review is not visible from anyone's main page, but can be accessed by directly typing the review id into the URL of the peerReviewView page or successfully searching for the file.
     202 Status:: The current state of the code review. The status dictates whether or not certain actions are possible. A manager can change the state at any time, and the author can close the review when it is open or reviewed. States include:
     203
     204 * ''Open for review'' - Initial state of the review, where reviewers can vote on the review and add comments.
     205 * ''Reviewed'' - Enough people have voted yes to push the review over the threshold limit. At this point the review can be submitted for inclusion by the author.
     206 * ''Ready for inclusion'' - The author feels, and his/her reviewers agree, that the review is ready for inclusion into the main trunk. At this point it is the manager's responsibility to verify the review, merge the changes with the main trunk, and close the review when finished. No voting is possible during this stage.
     207 * ''Closed'' - The review can be viewed, but no more voting is possible. The review is not visible from anyone's main page, but can be accessed by directly typing the review id into the URL of the !PeerReviewView page or successfully searching for the file.
    201208
    202209 Threshold:: This setting defines the number of positive votes versus total votes necessary for an author to submit a code review for a manager's approval.