0. Getting Started with Crucible

Crucible is a flexible application that caters for a wide range of work styles and team sizes. There are a number of different ways in which you can use Crucible for code reviews.

This page contains a simplified set of instructions for executing a one-to-one review with just two people. In this example, the code author wears "three hats", acting as review creator, moderator and code author, managing the review process as well as taking final responsibility for closing the review. The second person acts as the reviewer.

For instructions on workflow with more than two people, see 2. Requesting and Conducting a Review.

1. The Author Starts the Review

To begin, the code author sets up the review. There are a number of ways to do this. In this example, the author starts from the FishEye Changelog screen:

Screenshot: FishEye changelog

1. From the FishEye Changelog screen, the author clicks the Crucible icon next to the name of the changeset they would like reviewed, then click their name on the following screen. The Crucible Create New Review screen appears, where the author can create and issue the review.
   
   
   Screenshot: Crucible create new review
   
   
   
   
2. On the Crucible Create New Review screen, the author does the following:
   
   1. Types a name for the review in the 'Title' field.
   2. Checks that the author's name shows in both the 'Moderator' and 'Author' fields.
   3. Chooses the appropriate reviewer.
   4. In the 'Statement of Objectives' box, types a short description of the review objectives (if required).
   5. Clicks the button to finish the review creation (Note: the button here will make the review a draft review and store it under the drafts folder).
      Crucible will now send out an email notification to all the participants. This lets them know that the review is under way and prompts them to take action, providing a URL for direct access to the review. (You can also subscribe to an RSS feed.)
      
      

2. The Reviewer Comments on the Code

The reviewer will receive an email from Crucible (or an RSS feed update) with a link that they can follow to the review.

Screenshot: Crucible review notification email

1. When the reviewer clicks the URL in the notification email, the 'Crucible Under Review screen' opens.

Screenshot: Crucible under review

2. On the Crucible Under Review screen, the code changes under review are displayed, along with a list of participants. The reviewer clicks the arrow next to a filename to expand the code for in-line reviewing, reads the changes and simply clicks on any line to enter a comment on that line (multiple lines can be selected by clicking and dragging).

Screenshot: Making a comment in Crucible

The reviewer clicks the 'Post' button when each comment is finished.
The reviewer repeats this process for all files in the review. Reviewers can leave the session and resume it later — their work is automatically saved.
When the reviewer has finished their code review work, they click the button.

3. The Author Responds to the Comments

During the review process, the author/moderator can also make contributions, responding to reviewer comments and making corrections.

Screenshot: Comment threads in Crucible

4. The Author Closes the Review

1. When all reviewers have Completed their reviews, the author/moderator is notified via email. The author/moderator will then add any final comments, summarize and close the review.
   
   
2. The author/moderator clicks the link in the notification email, returning to the Crucible Under Review screen.
   
   Screenshot: Crucible under review
   
   
   
3. On the Crucible Under Review screen, the author/moderator will add final comments, then click the button. (if not all reviewers are finished, the author/moderator will be prompted to cancel or 'Summarize anyway'.) The Crucible Summary screen appears.
   
   Screenshot: Summarizing a review in Crucible
   
    
   
   
4. On the Crucible Summary screen, the author/moderator enters a summary of the review's results, then clicks . This closes the review, signalling the end of work.
   The closed review screen will load, displaying the summary and archiving the completed review as read-only.
   
   Screenshot: A closed review
   
   
    
   If the author/moderator ever needs to resume work on the closed review, they can simply click when viewing this screen. Doing this will return the review's status to "open".
   

For more information on workflow in Crucible and best practices for code reviews, see 2. Requesting and Conducting a Review.