This page last changed on Sep 03, 2008 by jgorycki.

The Atlassian IDE Plugin allows you to conduct Crucible reviews right there in your integrated development environment.

Before reading the information below, please make sure that you have installed the Atlassian IDE Plugin for IDEA, as described in the Installation Guide, and defined at least one Crucible server, as described in the Configuration Guide.

Crucible support automatically disabled for non-SCM projects

If a project is not under a source control management system, the plugin now automatically disables the Crucible options for that SCM.

On this page:

Icon and Popup showing Crucible Status

After you have defined at least one Crucible server in the plugin configuration panel, the Crucible status icon is displayed in the status bar. The icon has the following states:

  • Grey when there are no reviews awaiting your attention.
  • Grey with a green tick when there is at least one pending review which you have not yet accessed in the Crucible tab.

Screenshot: Crucible status icon in the IDEA status bar



Click the Crucible icon to open the Crucible tab. The icon state will be reset to grey.

In addition to the icon, a popup window notifies you of status changes and comments added to the reviews which affect you.

Screenshot: Crucible review notification

Accessing the Crucible Tab in IDEA

To open the plugin's Crucible tab in IDEA, you can do one of the following:

  • Click the Crucible status icon in the IDEA status bar.

  • Or:
    • Click the Atlassian Plugin control button in the IDEA side bar:


    • Then select the Crucible tab in the plugin window toolbar:

Contents of the Crucible Tab in the Plugin Window

The Crucible tab in the plugin window shows a number of review groups (such as 'To Review', 'Out For Review', etc) depending upon the filters you have selected.

Screenshot: Crucible tab in the plugin tool window



The above screenshot shows the dashboard-like display of Crucible reviews which the plugin offers within IDEA. The reviews are categorised into groups, as determined by the standard Crucible filters (such as 'To Review', 'Out For Review', etc). You can select one or more standard Crucible filters and also define your own custom filter. (See below for more information.) Then expand and collapse the views to suit your needs.

Toolbar in the Crucible Tab

The tool bar above the list of issues provides the following functionality:

  • — Open the plugin configuration panel.
  • — Get help on the usage of the Crucible tab (i.e. open this documentation page in your browser).
  • — Refresh the status of the review list by polling your Crucible servers.
  • — Open all the review lists in the Crucible tab, so that you can see the review line items as well as the filter headings.
  • — Close all the review lists in the Crucible tab, so that you can see only the filter headings.
  • — Create a custom Crucible filter. (See below.)
  • — Select your filter(s) from the list of standard Crucible filters. (See below.)
  • — Open the selected Crucible review in your web browser.
  • — Open the selected Crucible review in an IDEA window. (See below.)
Popup Context Menu for Reviews in the Crucible Tab

Right-click a line to show a popup context menu (pictured in the screenshot above) with actions that can be performed for the selected review:

  • View Review in Browser — Open the selected Crucible review in your web browser.
  • Open Review — Open the selected Crucible review in an IDEA window. (See below.)
  • Workflow actions, such as Complete Review, Summarize Review and Abandon Review — Move the review through the Crucible workflow statuses. (See below.)
  • Set Reviewers — Ask people to review your work.
Status of Reviews in the Crucible Tab

Different colours and font markings show the status of each review as follows:

  • Blue — Reviews which you need to review.
  • Grey — Reviews which you have already completed.
  • Green — Open reviews created or moderated by you.
  • Letters struck through (like this) — Reviews which have been closed or abandoned.
  • Black — Reviews which are not directly relevant to you.

In addition, the 'Reviewers' column shows the number of reviewers and whether each reviewer has completed the review.

  • A red square means that the reviewer has not yet completed the review.
  • A green square means that the reviewer has completed the review.

Filtering the Reviews Displayed

Screenshot: Reviews categorised by Filters



The above screenshot shows the dashboard-like display of Crucible reviews in the plugin's Crucible tab. The reviews are categorised into groups, as determined by the standard Crucible filters (such as 'To Review', 'Out For Review', etc). You can select one or more standard Crucible filters, as defined on the Crucible server. In addition, you can define your own custom filter locally in the plugin window. Then expand and collapse the filtered lists to suit your needs.

Using Filters Defined on the Crucible Server

To select one or more of the standard Crucible filters for display in the plugin's Crucible tab:

  1. Click the filter icon in the tool bar of the plugin's Crucible tab. A list of standard Crucible filters will appear.
  2. Select one or more of the standard Crucible filters, as prompted. The filter headings will appear in the Crucible tab.
  3. Expand and collapse the filtered lists to suit your needs, using the 'Expand All' and 'Collapse All' icons or the 'Expand' and 'Collapse' icons next to each filtered list.

Defining a Custom Filter

To define your own custom review filter for display in the plugin's Crucible tab:

  1. Click the 'Edit Custom Filter' icon in the tool bar of the plugin's Crucible tab. The filter definition panel will open, as shown below.

    Screenshot: Defining a filter in the Crucible tab of the plugin window



    The filter definition panel provides a number of criteria which you can use to filter the reviews.
  2. Select your Crucible server.
  3. Enter a title for your custom filter.
  4. Select one or more criteria.
  5. Click the 'Apply' icon to apply and save your filter.

The filter definition view contains the following icons:

  • — Applies the defined filter and saves it, so that it is used next time you restart your IDE.
  • — Cancels the definition of the filter and returns to the review list.

Performing a Review

This section tells you how to perform a review which someone else has assigned to you. Without leaving IDEA, you can:

  • Open the review and related source in the IDEA editor.
  • View your colleagues' comments in the context of the source.
  • Select the relevant lines and add your comment or reply to someone else's comment.
  • Track comments via highlights and marks in the right-hand gutter.
  • View the source diff to see what has changed.

Opening an Existing Review

To open a review in IDEA:

  1. Open the plugin's Crucible tab as described above.
  2. Choose your review filter as described above and expand the review filter groups until you see the review you want to work on.
  3. Right-click the review line and select 'Open Review'.
  4. The review opens in the IDEA 'Crucible Review' window, as shown in the screenshot below.
  5. Click the lines in the left-hand panel of the 'Crucible Review' window, to open the tree and view the files in the review. Existing review comments, if any, will appear in the right-hand panel.
    Screenshot: A review open in the 'Crucible Review' window

Viewing the Source

To open the source code which is under review:

  1. Open the review in IDEA as described above.
  2. Click the lines in the left-hand panel of the 'Crucible Review' window, to open the tree and view the files in the review.
  3. Double-click a file to fetch the source code from the repository. The source will open in the IDEA editor window.

Viewing the Diff

To view the change which is currently under review:

  1. Open the review in IDEA as described above.
  2. In the left-hand panel of the 'Crucible Review' window, open the branches of the tree to find the files in the review.
  3. Select the relevant file and click the 'Show Diff' icon in the toolbar.
  4. The diff view opens in a new window, as shown in the screenshot below.
    Screenshot: Viewing the diff

Adding a Comment or Reply

To add a comment, you can do one of the following:

  • In the right-hand tab of the 'Crucible Review' window, right-click the relevant line and select 'Add comment' or 'Reply'.
  • Or, in the right-hand tab of the 'Crucible Review' window, click the 'Add comment' icon.
  • Or, in the IDEA editor window, select and right-click on the relevant source line(s), then select 'Add Crucible Comment' as shown in the screenshot below.
    Screenshot: Adding a comment to source lines

Moving to the Commented Code in the Source View

To move to the commented code, you can do one of the following:

  1. Click the comments in the right-hand panel of the 'Crucible Review' window. The code view will scroll to the affected line.
  2. Or click the highlights in the right-hand gutter of the IDEA editor window, as shown in the screenshot below.
    Screenshot: Viewing commented code

Completing the Review

Once you have added your review comments, you should mark the review as completed. When all reviewers have completed their reviews, the moderator will summarise the review.

To complete the review:

  1. Open the plugin's Crucible tab as described above.
  2. Find the review in the 'To Review' list, as described above.
  3. Right-click the review line and select 'Complete Review', as shown in the screenshot below:
    Screenshot: Selecting a Crucible review for completion



  4. The 'Complete Review' dialogue appears, as shown below:
    Screenshot: Completing a Crucible review



  5. Click the 'Complete Review' button.
  6. When the list of reviews is refreshed, the review will disappear from your 'To Review' group.

Creating a Review

The plugin has full support for creating post-commit reviews from within IDEA. You can also create a patch review. Both are described below.

Creating a Post-Commit Review

To create a review of a committed change:

  1. In IDEA, open the 'Repository' tab of the 'Changes' tool window, as shown in the screenshot below:
    Screenshot: IDEA's Repository changes window



  2. Select the changelist you want reviewed.
  3. Right-click the changelist and select 'Create Review', or click the 'Create Review' icon in the toolbar.
  4. The 'Create Review' window will open, as shown below:
    Screenshot: Creating a Crucible review



  5. Enter the details, noting the following:
    • 'Save Review as Draft' — Tick this box if you want to keep the review in draft status. If this box is not ticked, the review will be approved immediately i.e. its status will be 'Under Review'.
  6. Click 'Create Review'.

Creating a Patch Review

To initiate a review of the code you have just created:

  1. Invoke the VCS Commit dialogue on the set of changes you want to have reviewed (file, directory, change set or project). For example, invoke the Subversion -> Commit if SVN is your version control system (VCS) of choice.
  2. This opens the 'Commit Changes' dialogue (shown below), to which the plugin adds a 'Crucible Patch... button.
    All other functionality of the 'Commit Changes' dialogue remains unchanged.
    Screenshot: Committing changes and creating a Crucible patch review



  3. Click the 'Crucible Patch...' button.
  4. The 'Create Patch Review' screen appears, as shown below.
    Screenshot: Creating a Crucible review



    The fields on the 'Create Patch Review' dialogue are the same as the fields in the Crucible web interface. Additionally, the dialogue contains a read-only view of the patch under review, in the Universal diff format.
  5. Enter the details, noting the following:
    • 'Save Review as Draft' — Tick this box if you want to keep the review in draft status. If this box is not ticked, the review will be approved immediately i.e. its status will be 'Under Review'.
  6. Click the 'Create review...' button to create the review on the Crucible server.

Adding a Changelist to an Existing Review

To add a changelist to an existing review:

  1. In IDEA, open the 'Repository' tab of the 'Changes' tool window, as shown in the screenshot below:
    Screenshot: Adding a changelist to a review



  2. Select the changelist you want reviewed.
  3. Right-click the changelist and select 'Add Revision to Review', or click the 'Add Revision' icon in the toolbar.
  4. Supply the details of the Crucible server and source repository as prompted, then click 'Add Revision'.

Moving a Review to Other Workflow States

The plugin's Crucible tab allows you to move a review through its workflow states.

  • Above we tell you how to complete a review.
  • In the same way, you can right-click a review and select the appropriate action, depending on the current status of the review.
    Screenshot: Actions on a review

RELATED TOPICS

Configuring the Plugin
IDE Plugin User Guide for IDEA

Refer to the Crucible documentation for more information about Crucible reviews.


Document generated by Confluence on Sep 04, 2008 17:39