Creating a review

Create a review

Begin by clicking Create review in the header and picking the project for the review (if you have multiple projects):

 

Click Create Review. 

Add content to the review

Click one of the content types to browse or search for files, branches and changesets you want to be reviewed:

Reviews should be created with care to get the best value from them. We've found it's best not to overload the review – they should be focussed on just a few necessary files.

See Adding content to the review for more details.

Click Edit Details to choose the reviewers and set other details for the review.

Choose the reviewers

You can choose individuals and groups, or allow anyone to join the review:

We've found it's best not to overcrowd the review – reviewers should be selected with care, and should be guided individually on what to look for.

See Choosing reviewers and Enabling the moderator role for more details.

Complete other details for the review

You can set other details for the review, including: 

• the title and description
• objectives – used to guide the reviewers on what to look for. See Setting default review objectives.
• a due date
• a reminder date
• linked reviews (if any)
• related JIRA issues (if any). 

The project, moderator and author are pre-selected.

Once you're finished, click Done. 

Start the review

The review will be displayed in draft mode. Here, you can check and edit the details as required.

Click Start Review to make the review available. See Performing the review.

When all the reviewers have performed their reviews, you can summarise and close the review. 

Considerations when creating reviews

Review effectiveness

Based on our own experience of over 13000 reviews, we have found that reviews with fewer files and reviewers are more effective. We have seen effects such as:

• Time spent reviewing each file decreases as the number of files increases.
• Reviewers spend less time reviewing as the number of reviewers increases.
• Reviewers find fewer defects as the number of reviewers increases.

We recommend that reviews be created with care to get the best value from them:

• Avoid overloading the review. Reviews should be focussed on just a few necessary files.
• Avoid overcrowding the review. Reviewers should be selected with care, and should be guided individually on what to look for.

Crucible performance

The performance of a Crucible instance can be seriously degraded if very large reviews are created.

To prevent a user from accidentally causing this, Crucible has a limit on the review content size when creating reviews. The limit is 800 file revisions.

Each version of a file in a review counts as one revision – so when a review is created for a single modified file, that is two revisions. Each subsequent change to the file you add to the review is one more revision. A 'whole file' in a review is only one revision.

If you really need to create a larger review, you can get your system administrator to set the crucible.review.content.size.limit property as described on the JVM system properties page, but remember that performance will be poor when creating and viewing very large reviews.

Adding an entire directory's contents to a Crucible review

To add an entire directory's contents to a Crucible review, you will need to search to find all the files, for example using "select revisions from dir /some/dir where is head and not is deleted", or similar logic.

 It is currently not possible in Crucible to add all the contents of a directory to a review with one click.