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.
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:
- Log in to FishEye/Crucible and either:
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. 添付ファイル 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.
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:
|リポジトリ||The repositories that contain files that can be reviewed.|
|作成者||The authors who have made changes in the selected repository.|
|ブランチ||This shows just the recent changes on the selected branch from the selected repository.|
|コミット メッセージ||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:
- You cannot add individual file revisions to a review, although you can remove them once the changeset is added. Click Remove all revisions from review to remove all.
- You can choose how reviewers will see the files you have added (described below) by clicking Add to Review as.
- You cannot add changesets that are entirely svnprops changes (i.e. it has no non-metadata changes). For details, see How do I force reviews to include SVN property changes?
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.
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.
- 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.
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
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 (UTF-8 is the default.) to choose the character set being used.|
|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.
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.
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.|
|アップロード||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
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.