Submitting AccuRev Elements to Code Review

The AccuRev Web UI can be installed as an Atlassian Crucible (Crucible) code review system plug-in.

Note: The integration between the AccuRev Web UI and Crucible is only available for versions of Crucible prior to 3.0. If, however, you are using Crucible 3.0 or later, you can add AccuRev contents to a Crucible review by using the AccuRev Plug-In for Atlassian Crucible, which is available at the
http://www.accurev.com/customer-support-resources/downloads/integration-packages site.

Overview

If this integration between AccuRev Web UI and Crucible has been implemented by your AccuRev system administrator, you can:

This section describes how to create and add to Crucible code reviews, and how to start Crucible from the Web UI. For more information about working with reviews in Crucible, see your Crucible documentation.

Back to top

Before You Begin

This section describes factors to consider prior to submitting AccuRev elements to code review.

Review Text File Extensions

Crucible uses the text/plain attribute in the raw-mime.types file to identify the files in a code review that it can treat as text files. While Crucible recognizes many extensions commonly associated with text files (.txt and .cpp, for example), consider reviewing the raw-mime.types file to ensure that it includes any special files you plan on adding to code reviews. For example, you might want to include log files (.log) and configuration files (.cfg) in code reviews as text files. If so, you need to add these extensions to the text/plain attribute in the raw-mime.types file as described in the following procedure.

To specify text file extensions in Crucible:

  1. Locate the raw-mime.types file in the directory where you installed Crucible.

  2. In the raw-mime.types file, locate the line that starts with text/plain. For example:

    text/plain asc txt java jsp asp cs idl cpp cxx c h pl pod py sh

  3. Add the extensions you need to this list.
  4. Save the raw-mime.types file.
  5. Restart Crucible.

For more information, see your Crucible documentation.

Note: AccuRev determines whether files without an extension are text or binary when you add them to a review or include them in a new review.

Crucible User Account Requirements

Your Crucible administrator must create a Crucible user account using your AccuRev user identity before you can submit an AccuRev element to code review. See your Crucible administrator if you have trouble logging in to Crucible.

Back to top

How Elements are Displayed in Crucible

When you submit an element to code review, AccuRev performs a diff operation to allow reviewers to compare versions of that element. As shown in the following illustration, versions used for the diff operation are displayed at the top of the Reviews tab, directly under the file name. Each version is displayed with its stream and version number -- in this example, 630/4 for the basis version and 630/5 for the head. Both versions display the AccuRev element ID (eid) -- in this example, 17726.

As in the AccuRev Diff tool, text is color-coded -- red to indicate text that has been removed from a version, green for text that has been added to a version. Sliders let you collapse the display to show only the contents of given version.

Tip: You can add the same element to an existing review multiple times, to create an iterative review. When you create an iterative review, each version you add is associated with its own entry, as shown in the following illustration:

See Adding AccuRev Elements to an Existing Crucible Review for more information about working with existing Crucible reviews.

Back to top

Which Versions are Diffed

As described in the previous section, AccuRev uses a diff operation to provide versions of a given element to Crucible. In most cases, AccuRev determines which Diff Against operation to use based on the active view at the time you select the element for code review. For example, if you select an element from the Timeline Diff view, AccuRev diffs the versions at the start and end of the time period you specify. The following table summarizes the type of diff operation that AccuRev performs based on the current AccuRev view.

AccuRev View

Type of Diff Performed

Description

Timeline Diff

Diff

Automatically diffs versions of the selected element at the start and end of the specified time period.

History Browser

Diff Against Previous Transaction

Automatically diffs the selected element against the version in the most recent transaction in which there was a content change.

Issue Edit Form

Diff Against Basis

Automatically diffs the selected element against the basis version.

Issue Diff View

Diff Against Basis

Automatically diffs the selected element against the basis version.

File Diff View

Diff

Automatically diffs versions of the selected element in the selected streams.

File Browser

User chooses one of the following:

  • Backed
  • Basis
  • My Changes

Allows you to choose which diff operation to use. See Use the File Browser to Choose the Diff Operation for more information.

For more information on AccuRev Diff operations, see Diffing Files in AccuRev.

Use the File Browser to Choose the Diff Operation

Unlike other views in which AccuRev selects the type of diff operation to perform when submitting elements to code review, when you submit an element to code review from the File Browser you can choose whether you want to diff against backed, basis, or just your changes as described here:

  • Backed Version: Compares your file with the version currently in the backing stream. For example, you might use this choice to see all the changes you have made to this file since you updated your workspace and starting working on the file. (And assuming no one else has promoted a new version to the backing stream in the meantime.) This might include the changes stored in several intermediate versions that you have created with keep.
  • Basis Version: Compares your file with the version that you started working with, before making your "recent" changes.
  • My Changes: Compares the workspace version with the common ancestor in the backing stream. This option is useful for files that have an (overlap) status because it identifies the changes in the workspace that did not come from the backing stream. The My Changes option is the equivalent of diffing against the last version that you merged with.

Back to top

Choosing Files for Review

AccuRev lets you submit elements to code review both explicitly (as when selecting one or more elements from the File Browser, for example) or implicitly (as when selecting all the elements in a change package associated with an issue, for example.

Consider the Issue Edit form shown in the following illustration. In this example, the Changes subtab is active, and a number of files have been selected:

Notice the two Code Review buttons () highlighted in this particular view -- one on the Issue Edit form toolbar, another on the Changes subtab toolbar. AccuRev responds differently depending on which button you click:

  • Clicking the Code Review button on the Issue Edit form toolbar submits to review all the elements associated with the current issue, regardless of whether or not you have selected any elements on the active subtab.
  • Clicking the Code Review button on the Changes subtab toolbar submits to review only those elements that you explicitly select (server.h, stl_hash.h, and stream.h in the illustration, for example). Note that you can use Ctrl+ click and Shift+ click to select multiple elements.

The following table summarizes whether an AccuRev view allows you to select elements implicitly, explicitly, or both.

AccuRev View Available Element Selection
Timeline Diff Explicit
History Browser
  • Explicit
  • Implicit
Issue Edit Form
  • Explicit
  • Implicit
Issue Diff View
  • Explicit
  • Implicit
File Diff View Explicit
File Browser Explicit

Note: Multiple elements, regardless of whether you select them explicitly or implicitly, are always placed in the same Crucible review.

Back to top

Creating a Crucible Review for AccuRev Elements

Use this procedure to create a new Crucible review for one or more elements under AccuRev control:

  1. In AccuRev, navigate to the browser or tab that manages the elements for which you want to create a Crucible review.
  2. Select the elements for which you want to create a Crucible review. See Choosing Files for Review if you need help with this step.

  3. Click the Code Review button () and choose Create Review from the drop-down menu.

    Note: If you are working in the File Browser, choose either Basis, Backed, or My Changes from the Create Review menu, as appropriate. See Use the File Browser to Choose the Diff Operation for more information.

    The Create Review dialog box appears:

  4. In the Name field, enter a name for the Crucible review.
  5. In the Project field, select the Crucible project in which you want to create the review from the drop-down list.

  6. Click Ok.

    Crucible opens in a new browser tab.

    • If you are already logged in to Crucible, the Edit Review Details page appears. Go to Step 8.
    • If you are not logged into Crucible, the Log in to Crucible page appears. Go to Step 7.

  1. In the Log in to Crucible page, enter your AccuRev username and password and click Log in.

    The Edit Review Details page appears. Go to Step 8.

    Note: Your Crucible administrator must create a Crucible user account using your AccuRev user identity. See your Crucible administrator if you have trouble logging in to Crucible.

  1. In the Edit Review page, optionally edit information about the review you are creating, including:

    • Adding reviewers

    • Entering a review objective and due date

  2. When you are finished describing the review, click:

    • Start Review if you want to start the review immediately
    • Done if you want to start the review at another time
  1. On the Reviews tab, click an element to compare versions.

Back to top

Adding AccuRev Elements to an Existing Crucible Review

Use this procedure to add one or more elements to an existing Crucible review.

Tip: You can also use this procedure to add a different version of an element that has already been added to a review to create an iterative review of that element.

  1. In AccuRev, navigate to the browser or tab that manages the elements you want to add to an existing Crucible review.
  2. Select the elements you want to add to the Crucible review. See Choosing Files for Review if you need help with this step.

  3. Click the Code Review button () and choose Add to Review from the drop-down menu.

    Note: If you working in the File Browser, choose either Basis, Backed, or My Changes from the Add to Review menu, as appropriate. See Use the File Browser to Choose the Diff Operation for more information.

    The Add to Review dialog box appears:

Note: The Add to Review dialog box does not list closed reviews.

  1. Select the Crucible review to which you want to add the elements.

  2. Click Add.

    Crucible opens in a new browser tab.

    • If you are already logged in to Crucible the Reviews tab appears; you can click the element you added to the review to compare versions:

    • If you are not logged into Crucible, the Log in to Crucible page appears. Go to Step 6.

  3. In the Log in to Crucible page, enter your AccuRev username and password and click Log in.

    The Reviews tab appears, as shown in Step 5.

Note: Your Crucible administrator must create a Crucible user account using your AccuRev user identity. See your Crucible administrator if you have trouble logging in to Crucible.

Back to top

Starting Crucible from within the Web UI

If your AccuRev system administrator has configured AccuRev as a Crucible plug-in, the Code Review button () appears in the Web UI toolbar, as shown in the following illustration.

To start Crucible from within AccuRev, click the Code Review button (). Crucible opens in a new Web browser instance, displaying the login page.

Once you have logged in to Crucible, you can set up reviews for files that are under AccuRev control. See your Crucible documentation for more information on creating reviews in Crucible.

Back to top