This is the documentation for Crucible 3.5. View the latest version of

Unknown macro: {spacejump}

or visit the latest Crucible documentation home page.

This page provides an overview of how to create a review in Crucible.

More information about the stages in creating a Crucible review can be found on these pages:

You can also create Crucible reviews in these other ways:

(info) Note that only people with the 'Create' permission can create a review.

 On this page:


Create a new review

Within Crucible, create a new review by clicking Create review in the header. Select the project for the review (if you have multiple projects), and click Create Review. 

 

Add content to the review

In the 'Add Content to Review' dialog, click one of the options to choose files or changesets for review. Crucible supports post-commit and pre-commit review types – these simply depend on the type of content you add to the review:

  • Post-commit reviews –  You want code changes that have already been committed to the SCM to be reviewed. In Crucible, you can browse and search for files or changesets in the SCM, which you then add to the review. Crucible can suggest files that should be considered for review, based on recent activity.
  • Pre-commit reviews – You want code changes that have not yet been committed to the SCM to be reviewed. You need to create a patch file for the code changes and then, in Crucible, add the patch to the review.

See Adding content to the review for more details. 

Browse Changesets – browse for SCM changesets
Explore Repositories – browse for SCM files
Search for Files – or changesets, in the SCM
Suggest Files – get Crucible to suggest files
Pre-commit – upload patch files
Attachments – upload any type of file

 

Note that Crucible supports iterative reviews – for both post-commit and pre-commit reviews you can update the review with new versions of files, and changesets, created after the review was started. Crucible allows the reviewer to see the different versions of updated files, so they can understand the changes that have been made. 


Click Edit Details to move to the next stage.

Edit the review details

 

In the Edit Review dialog you can set information for the review, including:

 

  • a title and description for the review
  • reviewers (as a mix of individual users and groups) - see Choosing reviewers
  • objectives for the review
  • a due date
  • a reminder date
  • the keys for linked reviews (if any)
  • the keys for related JIRA issues (if any). 

 

The project, moderator and author are pre-selected.


Once you're finished, click Done. 

 

The review will be displayed in draft mode. Here, you can check all the details and click to edit any that aren't correct. Once you click Start Review, the review is live.

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.

This suggests that reviews should 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.

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

 

 

 Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.