Variants

Issue variants are automatically-generated, internal variations of issues and their change packages that AccuRev creates to keep track of changes caused by patch, merge, and revert operations. In previous AccuRev releases, users were prompted to create tracking issues (or they might create totally different issues) and these issues could be difficult to relate to the original issue(s).

With variants, AccuRev now handles this bookkeeping automatically, and you generally do not need to deal with variants in your day-to-day work. But they are visible in a limited number of areas of the GUI, and this discussion explains why they are there and what they do for you. This section is directed at administrators and power users who need to understand the ramifications and history of patch, merge, and revert operations, or who want to understand how these operations are being recorded by AccuRev.

When AccuRev users prepare to make a change, they typically make the following determination:

•	Is the change entirely new, and generally unrelated to previous changes (such as a new feature, or a unique bug fix)? If so, create a new issue.

•	Is the change a continuation of a previous change (a tweak to the previously promoted enhancement, or a more comprehensive fix to a known bug)? If so, simply reuse the existing issue.

•

Is the change similar to -- but somewhat different than -- an existing change (for example, making an enhancement work on a new platform, so that much of the code applies, but with some fundamental differences). In this case, you may want to patch an existing change package into your current work, and this is where AccuRev will handle the bookkeeping automatically with a variant of the existing issue.

A variant appears as an issue number with a period and number appended to it. For example, if you patch issue #48 and AccuRev needs to create a variant to track that change, the variant will appear in a limited number of places in the UI as “48.1”.

Here are the places in the UI where you might see a variant:

•	the Version Browser

•	the Show Active Issues view:

•	the Changes tab of an Issue Form:

•	the CLI output from a cpkdescribe or cpkdepend command:

C:> accurev cpkdescribe -I 48 -p devel

Issue: 48
/var_test_1.txt      21/2 21/1

Issue: 48.1
/var_test_1.txt      16/3 20/1

•	the XML output from a cpkdescribe or cpkdepend command:

C:> accurev cpkdescribe -I 48 -p devel -fx

<?xml version="1.0" encoding="utf-8"?>
<acResponse>
  <issues>
      <issue>
          <issueNum>48</issueNum>
          <elements>
              <element
                 id="660"
                 real_version="21/2"
                 basis_version="21/1"
                 location="/var_test_1.txt"
                 dir="no"
                 elemType="text"/>
          </elements>
      </issue>
      <issue>
          <issueNum
             variant_num="1">48</issueNum>
          <elements>
              <element
                 id="660"
                 real_version="16/3"
                 basis_version="20/1"
                 location="/var_test_1.txt"
                 dir="no"
                 elemType="text"/>
          </elements>
      </issue>
  </issues>
</acResponse>

Again, it is important to emphasize that in your day-to-day work, you do not need to concern yourself with variants. AccuRev is handling this bookkeeping for you automatically. But you can view the existence of variants to help understand the history of changes packages.

Also note that although tracking issues are no longer required to record these kinds of changes, tracking issues are still available in certain scenarios if you prefer to use them. See Tracking Issues for more information.

Example

The following very basic example demonstrates a scenario in which AccuRev creates a variant:

1.	A new source file (app_src_rel_1a.txt) for a new application is created by the development team in North America, in workspace na_devel.

2.	This new file is promoted up the stream hierarchy against Issue #8 as the product is developed and released.

3.	A maintenance team in Asia makes a bug fix to this file for a specific customer, and promotes it part way up the stream hierarchy against Issue #9.

4.	A short time later, the maintenance team makes another small change to this file for a customer-requested enhancement, and promotes it part way up the stream hierarchy against Issue #10.

5.

Back in North America, the development team decides that they need to incorporate the bulk of the Issue #10 enhancement into their own work for the next release. So they choose to patch the Issue #10 enhancement into their development stream. They do this by dragging and dropping Issue #10 from the Active Issues view of the asia_devel stream, directly into the workspace of the developer in North America.

6.	This brings up the Diff view so the changes can be merged into the developer’s copy of the file. He chooses “Take their change” and saves the file.

7.	If you bring up this file in the Version Browser, you can see that the result of the patch is recorded in a variant of Issue #10 labeled “10.1”.

8.	Double-clicking the issue box for 10.1 brings up the Issue Form for Issue #10, focused on the Changes tab, showing the original change package for this issue (variant “0”), showing the basis and head versions from the original asia_devel workspace (#10).

9.	Clicking on variant “1” switches the Changes tab to show the patched basis and head versions from the na_devel workspace (#8):

10.	A similar display is available if you select the patched workspace and click Show Active Issues. The display comes up by default on the main issue:

11.	Click the “+” icon to expand the display of any variants, then select the variant line to show its change package entries in the lower pane.

Notes About More Complex Scenarios

The previous example showed a simple case of patching a single issue. More complex scenarios can have the following ramifications regarding variants:

•

Incomplete variants will cause the issue to be incomplete (see Incomplete Change Packages). A variant is considered to be “complete” only if all the relevant elements (eids) and all the relevant versions of those eids are present in the stream. If a variant is incomplete, then the change package for that issue is considered incomplete in that stream. This means that if you have defined a rule that prohibits the promotion of incomplete issues, an incomplete variant will prevent the promotion of its issue.

•

If you patch by dragging an issue from a stream where it has multiple variants, AccuRev creates a new variant in the target stream containing the contents of all the variants source variants. For example, say that stream “Stream1” contains issue #5, with variants 5.1 and 5.2. If you patch this issue to “Stream2”, Stream2 will end up with Issue #5 with a variant labeled 5.3, containing all the eids and versions that were contained in variants 5.1 and 5.2

Tracking Issues

In AccuRev versions prior to 6.0, tracking issues were required to track the changes that are now handled automatically by variants.

Although tracking issues are no longer required for many of these scenarios, they are still sometimes required after you cross-promote and patch multiple issues to a destination stream. And you may still choose to use them if for some reason you wish to have a patch operation (for example) tracked by its own unique issue rather than by a variant of an existing issue.

A description of how you might be prompted by the Change Palette to specify a tracking issue after a multi-issue patch operation is available in the example in Working with the Issue Change Palette.

 

A single tracking issue can keep track of the additional changes for any number of original issues. Thus, it makes sense to select Create Issue the first time you need to specify a tracking issue, and select Use Existing on subsequent uses of promote-by-issue in the same workspace. You might also need to select Use Existing if you are not allowed to create new issues.

Either way, an AccuWork Issue form appears, in which you fill in the fields of the new or existing tracking issue. As usual, click the form’s Save button when you are finished.

AccuRev automatically proceeds with your original Promote. It prompts you for a comment, then sends the versions from the workspace to the original destination stream. The cross-promotion of the original issue(s) is now complete.

Working with a Tracking Issue

The Stream Browser shows that the original issue (in our example, #8) has been promoted from the source stream (brs34_able) to the destination stream (brs34_baker). The tracking issue (#11) records the additional changes to issue #8’s elements that have been propagated to the destination stream.

AccuRev provides change package dependency tracking, which ensures that a Promote operation sends a self-contained, consistent set of changes to the destination stream. A tracking issue and the corresponding original issue(s) are connected by a change package dependency: the tracking issue depends on the original issue(s).

The best way to monitor such connections is with a Relationship field whose type is Track. (For details about Relationship fields, see Chapter A The Schema Editor (Administrators Only).) For example, when issue #8 is viewed in an Issue form, its connection to issue #11 might be displayed like this:

As with all change package dependencies, AccuRev warns you if you attempt to promote a tracking issue without its dependencies, the original issue(s). In this situation, do NOT click Proceed. It is important to always promote both the original issue(s) and the tracking issue at the same time. So the correct procedure is to Cancel, select both the original and tracking issues, then invoke Promote again.

As you propagate issues up (or across) the stream hierarchy, you must continue to obey this same rule:

Always promote original issues and the corresponding tracking issues at the same time.

If you attempt to Promote an original issue alone, without including its tracking issue, AccuRev prompts you to promote the tracking issue as well.