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 code 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, you start from the Fisheye source view of the file you want to review:

In the source view, choose Reviews > Create Review.

If there are multiple projects, the Select Project dialog opens:

Choose a project for this review from the drop-down list, then click Create Review.

The Edit Review Details dialog opens, you can create and issue the review:

In the Edit Review dialog, enter information needed for the review. This includes a title and description for the review, selecting reviewers, a due date and any related Jira issues. The project and author are pre-selected.

You can also add more content to the review, by clicking Add Content. See Adding content to the review.

When ready, click Done. The review will now be created as a draft:

The draft review opens. In the draft stage, you can check the contents of the review files and add notes for reviewers as comments. During the draft phase, no notification emails are sent out to reviewers. Once finished with the draft phase, click 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:

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:

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, signaling 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.

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.