The Crucible workflow

This page provides an overview of Crucible workflows, followed by a simple example showing a code review between two people.

On this page:

Roles
Crucible is a flexible application that caters for a wide range of team sizes and work styles. You will need to know about the basic roles used in Crucible:

• authors: Usually the creator of the code; the person who will act on the review's outcome.
• reviewer: A participant that will comment on the source files in the review, raising points and discussion on the work that was done.
• moderator: Usually the person who starts the review and is responsible for deciding the outcomes and closing it. The moderator is disabled for the "agile" permission scheme to simplify workflow.

Crucible Workflow

There are a number of different ways in which you can use Crucible for code reviews. The following diagram shows the basic workflow that applies to most Crucible code reviews.

Diagram: Workflow for One-to-One Reviews

Need more information? Read more about the different forms of workflow in Crucible.

Next, we explore an example workflow for a two-person code review in Crucible.

Example workflow: Two participant code review

This section describes a one-to-one review involving two people. In this example, the code author wears "two hats", acting as review creator, and code author, managing the review process as well as taking final responsibility for closing the review. The second person is the reviewer.

1. The author starts the review

To begin, the code author sets up the review. There are a number of ways to do this, but for this example, the author starts from the FishEye source view of the file he wants to review:

Screenshot: Opening a review from the FishEye Source view

From the FishEye Source view, the author chooses Reviews > Create Review. If there are multiple projects, the Select Project dialogue opens.

Screenshot: The Select Project dialogue

In the Select Project dialogue, you are prompted to choose a project for this review from the drop-down list. Once the selection is made, the author clicks Create Review. The Edit Review Details dialogue opens, where the author can create and issue the review.

Screenshot: Creating a review in the Edit Review Details dialogue

In the Edit Review dialogue, the author enters information needed for the review. This includes entering a title and description for the review, selecting reviewers, a due date and the key for a related JIRA issue (if any). The project and author are pre-selected.

The author can also add more content to the review, if they wish, by clicking Add Content. See Adding content to the review.

When finished, the author clicks Done. The review will now be created in a draft form.

Screenshot: A new Crucible review

The draft review opens. In the draft stage, the author can check the contents of the review files to ensure they are correct and put in any notes for reviewers as comments. During the draft phase, no notification emails are sent out to reviewers. Once the author is finished with the draft phase, he clicks Start Review.

The review will now be started and a notification email will go out to all 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.

2. The reviewer comments on the code

The reviewer will receive an email from Crucible with a link that they can follow to the review.

Screenshot: A Crucible review notification email

When the reviewer clicks the link in the notification email, the Crucible Review screen opens.

Screenshot: The Crucible Review screen

The Review screen displays the source files that are under review. The reviewer clicks file names to see the code to be reviewed. As the reviewer reads the changes, they can add comments:

• Click Add a general comment (under 'General Comments' on the Review screen) to comment on the overall review.
• Click Add a file comment (just above the source code listing) to add a general comment about a source code file.
• Click on any line in the source file to enter a comment there (multiple lines can be selected by clicking and dragging).

The reviewer clicks Post to add the comment to the review.
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 Complete.

3. The author responds to the comments

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

Screenshot: Comment threads in Crucible

4. The author closes the review

When all reviewers have "Completed" their reviews, the author is notified via email. The author clicks the link in the notification email, returning to the Review screen.

The author can then add any final comments, and click Close when finished.

This closes the review, signalling the end of work. A final email notification will be sent to the review participants, informing them that the review is now closed. The closed review screen will load, archiving the completed review as read-only.

Screenshot: Viewing a closed review

If the author ever needs to resume work on the closed review, they can simply click Reopen when viewing this screen. This returns the status of the review to "Open", without changing the staus of existing reviewers. Click Edit Details to add reviewers or to change other details of the review.