This page last changed on Jul 02, 2009 by rosie@atlassian.com.

This page explains how to select files that will be included in a Crucible review.

The Manage Files dialog allows you to select and modify which files make up the review. In the Manage Files dialog, the author selects the source files they want to include in the review, by clicking the checkboxes next to the desired files. Once finished, the author clicks 'Done'.

On this page:

Overview of the Manage Files Dialog

The 'Manage Files' dialog is first displayed when you are creating a review. Once a review has started, (as the creator or moderator) you can reopen the dialog by clicking the Manage Files button on the Review toolbar.

The left navigation bar allows you to select and locate different files for the review including files from repositories, patch files and uploaded files. The screenshot below shows the view shown when checking the list of currently selected files; the 'Review Content' view.

Screenshot: The Review Content View Under the Manage Files Dialog

See the table below for detailed instructions on the various links on the left navigation bar of the Manage Files dialog.

Left Navigation Bar Links In The Manage Files Dialog

Left Nav Title Explanation Special Conditions
Review Content Shows the list of files selected for review and allows you to manage them.  
Change Sets Allows you to choose change sets from a Source Code Management (SCM) repository and add them to a review. Only appears when FishEye is installed.
Files Allows you to choose files from a Source Code Management (SCM) repository and add them to a review.  
Search Allows you to search a Source Code Management (SCM) repository for files or change sets and add them to a review. Only appears when FishEye is installed.
Suggestions Analyses the list of files in the current review and makes suggestions based on certain logic (for example, suggesting a newer version of a file if one exists).  
Patches Allows you to upload patch files to a review.  
Uploads Allows you to upload any file to a review, including binary files and files outside of a Source Code Management (SCM) repository.  

When a red dot is shown next to a file name or changeset name, it indicates that for the file you have selected, a newer version exists. When a number is shown next to the file or changeset name, it indicates the number of comments that have been made. Numbers in brackets show unread comments.

Screenshot: Red Dot and Comment Counter in the Manage Files Dialog

Selecting Changesets for Review

To add changesets to a review, open the 'Changesets' view by clicking the "Changesets" option on the left navigation bar in the Manage Files dialog. The Changesets view opens.

Screenshot: The Changesets View in the Manage Files Dialog

By default, Crucible presents a list of the author's changesets in reverse chronological order. You can see other changesets by changing the options at the top of the screen.

Click the checkbox next to a changeset ID to add the entire changeset, or the checkboxes next to file names to add or remove individual files. Clicking the checkbox of a parent item will select or de-select all of its children. Click 'Remove all revisions from review' to remove all.

Options for Adding Changesets

Repository This is a list of the repositories that contain the files that can be reviewed. If the repository you require is not in the list then it has not been added to FishEye. Please contact your Crucible/FishEye administrator.
Author This contains a list of all the authors who have made changes within the repository. When creating a review, this will default if possible to the username of the user authoring this review and will therefore show their changesets.
Branch This will only show files and recent changes on that branch from the repository set above.
Tag This will only show files and recent changes tagged.
Add to Review As Choose the form of the review; see full details.
Go to Changeset Allows you to jump to a particular change set by entering its title and pressing Enter.

Understanding the Icons Shown with Changesets

To help decide what files are to be placed under review, you can click the icons next to the files to gain further information about them before they go out for review:

Clock icon or the file URL A view detailing the history of this particular file.
Changeset ID next to the file URL A view of the complete file. Amended lines are highlighted on the left in yellow.
Down arrow icon Option to download the file.
Change Indicator (+n -n) This shows how many lines have been amended (e.g. +3 -2) and also what type of change has been made. If it says 'diffs' then you can click this to see the differences in the file between the revisions.

After you have chosen the files, click the 'Review Content' option on the left navigation bar to view the files that are included in the review.

Selecting Files for Review

To add files to a review, click the 'Files' option on the left navigation bar of the Manage Files dialog. The Files view opens.

To find a file, browse the folders by clicking the relevant folder. The folders by default are sorted by path name but can sorted by last-commit or first-commit. To choose a file for reviewing, click the checkbox to the left of the filename and if required the revision number.

Caveats:

  • Empty folders will be greyed out.
  • If the folders contain empty folders then a toggle option called 'Hide Empty' will appear under the 'Sort' options.
  • To see or ignore deleted files, you can click the 'Hide' and 'Show' options located above the file names on the left.

After you have chosen the files, click the 'Review Content' view to see the files that are included in the review.

Screenshot: Files View in the Manage Files Dialog

Searching in the Manage Files View

The 'Search' view is available when using FishEye with Crucible.

Screenshot: The Search View in the Manage Files Dialog

If you are not certain about which changesets/revisions/files to include in a review, use the Search view to find them.

Adjust the search filters to find the files you need. If the simple filters are not enough, read about EyeQL queries in the FishEye documentation.

After you have chosen the files, click the 'Review Content' view to see the files that are included in the review.

Read the FishEye documentation for more information about the searching your repository.

Viewing the Content Selected for Review

To look at the list of content selected for the review, click the 'Review Content' option on the left navigation bar. The Review Content view opens.

In this view, you can look over the list of items selected for review. For each item, you can click its name to see which revisions are included in the review. In that view, you can also remove individual files or content items completely (by clicking the small red 'X' icons over each item), as well as adding or removing individual revisions.
Note that you cannot removed items when they already have comments added to them.

Screenshot: The Review Content View in the Manage Files Dialog

Using the Suggestions Feature When Adding Files to a Review

Crucible can make intelligent suggestions when you are creating a review. Once you have selected some files, click 'Suggestions' in the left navigation bar to let Crucible analyse your selection and make some recommendations to you.

The Suggestions feature logic is based around the following:

  • Most recent versions: If a newer version of a file exists, Crucible will suggest that you add it to the review.
  • Similar files: Files with a similar filename may be of relevance to your review; Crucible will show them to you.

Screenshot: The Suggestions View in the Manage Files Dialog

Adding Patch Files to a Review

For a full explanation of the 'Patch View' functions, read about creating a patch review.

Uploading Files to a Review

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

The 'Upload' view contains various controls to help you do this. These are listed in the table below.

File to review By clicking 'Browse', you can find the file you want to review.
File to diff with By clicking 'Browse', you can find the file you want to compare against the first file.
Comment Here, you can put in an identifying comment about this particular piece of work.
Author username Enter the author username into this field.
Character Set (if any) In the drop-down list, you can choose the character set being used. 'US-ASCII' is the default.

When you've made your selection, simply click the 'Upload' button. Once complete, a list of uploaded files is displayed at the bottom of the screen.

Screenshot: Upload View in the Manage Files Dialog

Choosing the Form of the Review

When adding files to a review, you can set the form of review taking place. Several options are listed along the top of the 'Manage Files' dialog, in the Add to Review as: drop-down menu:

Screenshot: File Addition Options in the Manage Files Dialog

Whole File Adds the entire file with all content, rather than just a diff with context.
Diff to Previous Version This is the default behaviour, and how previous versions of Crucible worked by default.
An Iteration This allows you to add multiple revisions of a file to one review and compare them in-review, in context with the change history.
Diff to Last Reviewed Version This creates a review with a diff to the last reviewed changeset.
Diff to... (a particular revision) This allows you to specify the review to show the differences between two specific versions of a file. This is useful in various situations. For example, you may want to review all changes since you branched your project.
Whole file The review content is not limited by changesets, showing the entire file contents.

Document generated by Confluence on Jul 09, 2009 19:51