Downloads (PDF, HTML & XML formats)
[Crucible Knowledge Base]
Documentation for Crucible 3.0.x. Documentation for other versions is available too.
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:
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.
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.
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.
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
On the Crucible Review screen, the code changes under review are displayed. The reviewer clicks file names to expand the code for in-line reviewing. As the reviewer reads the changes, they can simply click on any line to enter a comment there (multiple lines can be selected by clicking and dragging).
The reviewer clicks Post 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 Complete.
By default, an email is sent to participants every time a comment is posted. This is an individual setting. Each reviewer can configure their own profiles to adjust the list of events that will trigger email notifications.
During the review process, the author can also make contributions, responding to reviewer comments and making corrections.
Screenshot: Comment threads in Crucible
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 will then add any final comments, then 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. Doing this will return the review's status to "open".
4 Comments
Kevin Shine
Fine. What if the reviewer suggests a code change and then the file is changed. In the review you cannot see the change, so should you close the review and open another one or is this all done somehow in 1 review? Please explain or point to where this is detailed in the documentation.
Anonymous
I looks like that's handled with iterative reviews: Iterative Reviews
Anonymous
How do I create a review for some branch or range of commits (Git repo)?
Right now if someone develops a feature in a feature-branch and creates 20 commits I have to check (painfully slowly) 20 checkboxes from Add Content dialog for every single commit.
Anonymous
Similar question to the above – is it possible to setup a review of the changes defined by:
git diff <branch1>...<branch2>
Basically to review the what would happen to branch1 were you to merge branch2 in.