Adding content to the review

This page explains how to add content, such as files and changesets, to a Crucible review.

We've found that reviews with fewer files and reviewers are more effective. Reviewers spend less time reviewing each file as the number of files increases, so don't overload the review – help your reviewers to focus on just the essential files.

Overview

Crucible supports post-commit and pre-commit reviews, depending on the type of content you add to the review:

  • Post-commit reviews – for code changes that have already been committed to the SCM. 
  • Pre-commit reviews – for code changes that have not yet been committed to the SCM. Create a patch file for the code changes and then add the patch to the review.

Crucible also supports iterative reviews – you can update the review content with new versions. The reviewer can see the different versions of the files, so they can understand the changes that have been made. 

To add content to a review:

  1. Log in to Fisheye/Crucible and either:
    • Create a new review, as described on Creating a review, or
    • Open an existing review, for which you are the creator or moderator, and click the 'Add content' () button.
  2. In the 'Add content to Review' dialog, click the option for the type of content you wish to add:

    Post-commit reviews
    Browse changesets Allows you to choose changesets from a repository. Go to Selecting changesets for review below.
    Choose branches Allows you to choose branches from a repository. Go to Choosing branches for review below.
    Explore repositories Allows you to browse for files in a repository, when Fisheye is installed. Go to Selecting repository files for review below.
    Search for files Allows you to search a repository for files or changesets, when Fisheye is installed. Go to Searching for files to review below.
    Pre-commit Allows you to upload patch files to a review, so you can review code changes that have not yet been committed to the SCM. Create a patch file for the code changes and then add the patch to the review. Go to Adding patch files to a pre-commit review below.
    Attachments Allows you to upload any file to a review, including binary files and files outside of a repository. Go to Adding attachments to a review below.

Changesets

Click Browse changesets in the 'Add content to Review' dialog to add SCM changesets to your review.

By default, Crucible displays a list of the review creator's changesets. You can see other changesets using the following options:

Repository The repositories that contain files that can be reviewed.
Author The authors who have made changes in the selected repository.
Branch This shows just the recent changes on the selected branch from the selected repository.
Commit message Filter for specific commit messages.
Scroll to changeset Jump to a particular changeset by typing part of its changeset ID.

Select the checkbox next to a changeset ID to add the entire changeset. Note that:

Branches

When you select a branch to be reviewed, Crucible displays a list of the changesets on the branch that have not yet been merged to the base branch – you see a quick preview of the changesets that will get added to the review.

Reviewers will only see the changes that have been made on the branch – irrelevant changes are hidden. Furthermore, your reviewers can continue reviewing even if some changes are merged from the branch.

To add a branch to a review, click Choose branches on the 'Add content to Review' dialog, then choose the repository that has the branch you want reviewed:

Now choose the branch:

You'll see a list of the recent commits. If that all looks good, click Add branch to review to finish.

You can also create a branch review directly from the activity stream. Once your changeset is indexed and visible in the activity stream, just click on the cog and choose Create review for branch, and continue as above.

Your branch review is quickly and automatically updated whenever new commits are made to the repository branch – review participants get notified and are able to resume their reviews immediately.

You can remove files from a branch review and they won't be added again on the next update, unless there were further changes to those files. Furthermore, your reviewers are able to continue with the review even if some of the changes are merged from the branch to the base branch.

Repository files

Click Explore repositories on the 'Add content to Review' dialog to browse the SCM repositories for files to add to your review:

  • By default, the folders are sorted by path name but they can also be sorted by last-commit or first-commit.
  • To select a particular revision of a file, select Load full history... from the revision number list. This will refresh the available options.
  • You can choose how reviewers will see the files you have added, as described below.

Note that:

  • Empty folders are greyed out.
  • The 'Cog' menu has options to Hide empty directories and to Hide deleted files.

Search for files

Click Search for files on the 'Add content to Review' dialog to search for files to add to your review.
(warning) Search is only available when using Fisheye with Crucible.

Adjust the search filters to find the files you need. If the simple filters are not enough, consider using EyeQL queries.

Read more about searching your repositories in the Fisheye documentation.

You can choose how reviewers will see the files you have added, as described below.

Patch files for a pre-commit review

Click Pre-commit on the 'Add content to Review' dialog to add previously created patch files to a pre-commit review.

Choose an upload method:

Select file from the file system Charset – click the edit icon () to choose the character set being used. UTF-8 is the default.
Choose File – click to to browse for the file that you want to add to the review.
Paste text from clipboard Patch text — paste your copied text in this text area.

For more information see Creating patch files for pre-commit reviews.

Patch anchoring

A short-coming of patches for code review is the reduced context around code changes because the patch does not include all lines of code from the file. Crucible 'patch anchoring' overcomes this by searching for the relevant file content in the connected repositories, and automatically anchoring the patch to the trunk or the branch with the most recent commit activity. Crucible can then seamlessly display more context, as required.

See Using Crucible patch anchoring for more information.

Attachments

Click Attachments on the 'Add content to Review' dialog to add attachments to your review.

You can attach additional files to be used in the review, including binary files, images or code files that are not stored in a version control repository. 

Charset Click to choose the character set being used. UTF-8 is the default.
Choose File Browse for a file that you want to add to the review.
Upload Browse for a file that you want to use as the base of a diff with a previously attached file.

To add another iteration of a file, upload a different version of the file with the same filename. It will be added as a new version.

Choose how reviewers see the content

When you add files to a review, you can set how reviewers will see the files, for example as the whole file, or as a diff.

Choose one of the following options from the Add to Review as list:

Diffs This is the default. This allows you to add multiple revisions of a file to one review and compare them in-review, in context with the change history.
Whole Files Adds the entire file with all content, rather than just a diff with context.
Diffs to Last Branch Point This adds files with a diff to the revision each file was last branched.
Diffs to Last Reviewed Version This adds files with a diff to the last reviewed changeset.
Diffs to... (a particular revision) This allows you to specify the file to show the differences between two specific versions of a file.

Click Done once you have finished selecting the required files. The files will be added to your review and the review will be displayed.

Last modified on Nov 28, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.