How to use Malevich
A code review starts with a (non-default) change list (in perforce), or a shelveset (in TFS). The reviewee sends it to the reviewers using a command line too called review.exe:
review 5454 alice bob
This uploads files from change list 5454 and sends mail to alice and bob to code review them. The reviewers can be added separately by running review.exe multiple times, for example, the command above is equivalent to:
review 5454 alice
review 5454 bob
In the examples above, alice and bob were added to the list of reviewers for a change list. It is possible to invite people to join code review without adding them to the list of reviewers yet, for example, when a number of a people are asked, but only one or two are expected to participate. The email sent in this case has an option for a person to add him or herself as a reviewer. This is especially useful for the distribution lists. To use this feature, prefix an email alias with an "--invite" flag. In the example below, alice and bob are added as reviewers, and people from monsterreviewers list are invited to join the review as well:
review 5454 alice --invite monsterreviewers bob
Invoking review multiple times if the change and the files behind it did not change does not produce any side effects. However, if the change manifest or description did change, the files were updated, then the new change and/or the updated files are uploaded, allowing the reviewer see multiple changes to the same file, for example, as reviewee makes modifications requested by code reviewers on review iterations.
The reviewers then get emails inviting them to do code reviews (or accept a code review invitation, depending on how they were invited). The mail includes a pointer to a web site for the specific change list. The reviewers do not need to have access to the source code - Malevich web site contains all the files they need. Clicking on a change list link produces the page for the change list, which shows basic description of a change and a list of files.
Clicking on a file shows the diff view, where the reviewer can see side-by-side differences between any two uploaded versions of the file. Clicking on a line allows the reviewer to enter a comment.
A comment sticks to a line within a given version
of a file. A version (as opposed to source control revision) is a file as modified by the developer and submitted with the review tool. Each text file has at a minimum one version in the database for added files, and two versions (the base revision and the change) for the edited files. As the review process progresses, some files may change multiple times, and be re-uploaded to the server, creating new versions.
Multiple comments made by a single user constitute a review iteration. Initially, comments are only visible to the user who makes them. The author of comments can edit and even remove them by clicking on one of his or her comments, and then either changing the text in the text field, or clicking "Remove". When all commenting is done, the comments must be submitted from the change view. This makes them all visible to the person who requested the review, as well as all the other reviewers, but at this point they become read only - they cannot be changed or removed even by the author. We will call a group of such submitted comments a review iteration
When a reviewer submits a review iteration, he or she can render a verdict on the change - one of "LGTM" (Looks Good To Me - ready to submit), "LGTM with minor tweaks" (almost good - feel free to submit it after fixing a few things in the review; no further reviewing is necessary), "Needs work" (the change should be refined further, and the reviewer would like to look again when it's done), and "Non-scoring comment".
After submitting a review iteration, a reviewer can immediately create a new one, if he or she had forgotten a few comments that should be made. When submitted, it just creates another entry in the review history. All comments from all submitted iterations by all reviewer (and the reviewee) are visible in the file view.Note:
anyone can leave a comment through Malevich, not just the reviewers that were invited. These comments by default get a non-voting status, unless the person making these comments joins the rank of reviewers by clicking "I want to review this change list" link in the change list view.
When a review iteration is submitted, all reviewers and the reviewee get notified via email. The reviewee can then go and look at the comments on the web site. He or she will have the same view as the reviewers. The reviewee (and anyone else) can respond to the comments by clicking on the comment, a leaving a note in the text box that appears. It is customary to mark the comments that has been implemented as "Fixed", and respond to the ones that were not by explaining why.
After responding to the comments, the reviewee uploads the modified files to the system by running review.exe again:
There is no need to list the reviewers again at this point, unless a new ones are added (in which case, only the new reviewers are listed.
After submitting the new versions of the change list (assuming that the changes were made), the reviewee goes to the web site, and submits his round of responses to the comments (which may simply be "All fixed - please look again!") from the change list view. The reviewers get the email, and the next review round begins.
Eventually, when everybody has signalled their satisfaction with the results, the author of the change submits it. When this is done, the review can be closed as follows:
review close 5454
If the change list has been deleted, so should be the review:
review delete 5454
Every Malevich user also has his or her personal dashboard - visible at the root of the Malevich web site - that list all his or her outstanding reviews, where the user is either a reviewer, or a reviewee.