Complex Change Package Entries

All change package entries are recorded in terms of real versions (those created in users’ workspaces), even though there may be corresponding virtual versions (created by promoting the real versions from workspaces to dynamic streams). In all the examples shown above, each change package entry is a series of consecutive real versions created in the same workspace — that is, each change package entry records a particular patch to the element.

In this topic:

Change Package Entries Overview

The change package facility can also track ongoing changes to elements — changes made at different times, and in different workspaces. To support this capability, AccuRev defines a change package entry in a more general way than a patch:

A change package entry for an element consists of all the real versions in the element’s version graph between a specified basis version and a specified head version. Between-ness is determined both by direct predecessor-successor connections (created, for example, by Keep) and by merge connections (created by Merge). Patch connections are not considered in this determination; the basis version itself is not part of the change package entry.

The following Version Browser excerpts show the range of complexity that a change package entry can have. In fact, these excerpts show how the same change package entry can change over time, becoming more complex.

These illustrations suggest the following definition for a change package entry, which is equivalent to the definition above:

A change package entry for an element consists of the element’s entire version graph up to the specified head version, minus the entire version graph up to the specified basis version. For these purposes, the version graph includes direct predecessor-successor connections and merge connections, but not patch connections.

Back to top

Notation

To help explain how AccuRev performs “change package arithmetic” to combine and update entries, we’ll use a simple notation. Suppose a change package entry contains the set of an element’s versions defined by these specifications:

the head version is H
the basis version is B

We’ll use the ordered pair [B,H] to indicate this change package entry.

Back to top

Combining Two Change Package Entries

Now, suppose a new change is to be combined with the existing change package entry [B,H]. There are several cases, each handled differently by AccuRev:

Case 1: [B,H] + [H,X] — This simple case typically arises when you think you’re done with a task and record your work as change package entry [B,H] — but it turns out that more work on the same element is required. So if you (or a colleague) start where you left off, with version H, and make changes up to version X. Then, you want to incorporate the new set of changes [H,X] into the same change package.

In this case, it’s clear that the two series of changes can be viewed a single, uninterrupted series — starting at version B and ending with version X. That is:

[B,H] + [H,X] = [B,X]

Accordingly, AccuRev updates the change package entry automatically — keeping B as the “Basis Version” and changing the “Version” from H to X.

• Case 2: [B,H] + [J,X] (where H is an ancestor of J: “change package gap”) — This case typically arises when you do work on a task at two different times, and someone else has worked on the same element in between.

  In this example, a colleague updated her workspace to bring in your original changes, created versions 9 and 10 in her workspace, and promoted her changes. You then updated your workspace to bring in her changes, and made a new set of changes.

  When AccuRev tries to combine the change [B,H] and the change [J,X] into a single change package entry, it detects that version H and version J are not the same, but that H is a direct ancestor of J. Thus, there is a simple “gap” in the potential combined change package entry (in this example, consisting of your colleague’s versions 9 and 10).

  Probably, your colleague was not working on the same task when she made her changes. (If she had been, she would have added her changes to the same change package, as in Case 1.)

  Accordingly, AccuRev treats the two change set entries as separate segments, and the in-between versions that are associated with other work can be safely ignored.

• Case 3: [B,H] + [K,X] (where H is not an ancestor of K: “change package merge required”) — This case typically arises when developers in workspaces that do not share the same backing stream try to use the same change package. There is no simple “gap” between the existing change package entry and the new one — which means there is no way to combine them into a single change package entry, according to definitions in Complex Change Package Entries.

  

  AccuRev signals this situation with a “change package merge required” message, and cancels the current operation.

  

  You can remedy this situation by performing a merge at the element level. (There is no merge operation defined at the change package level.) In the example above, merging version H and version X would create a new version; a change package entry with the new version as its head can be combined with the existing entry.

Back to top

Change Packages, Segments, and Dependencies

An issue dependency occurs when one issue has some kind of requirement on the contents of another issue. For example, consider a file that is being edited by two different people for two different issues. One person edits the file and promotes it under Issue #1. The second person takes this updated version, makes further edits and promotes it under Issue #2.

A problem can occur when the first person then wants to make additional changes to the same file under Issue #1. The changes from Issue #2 are now an unwanted dependency for Issue #1: They might not have anything to do with Issue #1, but they must be included by “spanning the gap” in any subsequent promote operation.

Not only does Issue #2 have nothing to do with Issue #1, but prior to AccuRev 6.0, it became a part of Issue #1 after “spanning the gap”. If Issue #2 has, say, three other files, then those would become dependencies of Issue #1 that are not desired.

AccuRev 6.0 can now handle this situation for you through the introduction of multiple segments.

AccuRev treats contiguous versions of a file as a segment. Each segment can be tracked and handled independently. That way, multiple promotes for Issue #1 can be tracked, and having a “gap” caused by an intervening promote of Issue #2 does not cause a problem. You can think of each segment almost as a separate patch (not the AccuRev patch command, but a generic, development patch).

AccuRev handles all the record-keeping automatically, and you no longer need to deal with the changes introduced by Issue #2.

Back to top

Comparing Versions Across Segments

If a text file has multiple segments because it has been promoted against different issues and you want to compare only the versions of a file that were promoted against the same issue, you can accomplish this by using the Diff Across All Segments option. When you use this feature, the diff shows all changes to the file that were promoted against a single issue while ignoring any changes to the file that were promoted against a different issue.

To understand the purpose of the Diff Across All Segments option, imagine the following scenario:

1. You create a file and promote it against issue 5.
2. A co-worker makes changes to the file for unrelated reasons and promotes the file against a different issue, say issue 7.
3. You make further edits to the file and promote it against issue 5 once more.
4. You can view all the edits that you have made to the file by opening issue 5, selecting the Changes tab, selecting the file, and choosing Diff Across All Segments. In this case, AccuRev displays a diff that shows only those changes made to the file that were promoted against issue 5.

For example, suppose you create the following file called intro_example.java:

You then promote intro_example.java to issue 5. At this point, a co-worker, who has been assigned to add comments to source code, edits intro_example.java and adds comments so that the edited file now appears as follows:

Your co-worker now promotes intro_example.java against issue 7.

At this point, you make more edits to intro_example.java in order to create a Spanish version of the file and you once again promote the file against issue 5.

In this example, intro_example.java is now composed of the following segments:

To view all the edits you have made to intro_example.java, and only those edits, you would take the following steps:

1. Select Issues > Open Issue.

2. In the Look Up Issue dialog box, enter 5 in the Enter Issue Number field and click Ok.

3. Select the Changes tab.

   The file intro_example.java appears with a plus sign (+) aside it, indicating that the file contains multiple segments:

   

4. Select the intro_example.java file and choose Diff Across All Segments:

   

The resulting diff shows all the changes to the file that have been promoted against issue 5:

The changes shown do not include the comments that were added to the file and promoted against issue 7.

The Diff Across All Segments option is inactive for files that contain only a single segment. For more information about other types of diff operations in AccuRev, see Diff, Merge, Patch, and the Change Palette.

Back to top

Change Package History

How do you display the changes that have been made to a change package? Use the Change Package History icon on the Issues toolbar:

This brings up a list of all changes that have been made to the change package, including promotions, and elements that have been added (cpkadd) or removed (cpkremove).

For information about specific changes, select the transaction in the upper pane and view the elements associated with that change in the lower pane.

Back to top

Association with Issue Record

An issue record's change package differs from its user-defined fields (Status, Severity, Description, etc.). When you change the value of a user-defined field, the Save button is enabled in the edit-form toolbar. You can discard the change by closing the edit-form tab without performing a Save. But the commands that create, modify, and delete change package entries take effect immediately. There is no way to discard such changes, and you do not need to explicitly save them. (You can Remove a change package entry altogether, but you can't undo the adding of a new change to an existing entry.)

Change packages do not participate in AccuWork's issue-history capability. Modifications to a change package do not appear in the Issue History subtab of an Issue form, although you can use the Change Package History feature described above.

Back to top

Unaffiliated Changes

It is possible to end up with changes that are not associated with any issue. For example, somebody might decide that a file does not belong to an issue and remove it from the change package.

Whenever you remove an element version from a change package, either from the GUI or from the CLI cpkremove command, you should immediately follow the operation with a Send to Issue on the removed element, to prevent it showing up as an Unaffiliated Change.

In the Stream Browser, select Show Active Issue mode:

If any unaffiliated changes exist in the stream, the issue table gains an extra row labeled “NONE”. If your schema is configured to show the Short Description field, “UNAFFILIATED CHANGES” is displayed here. Double-clicking this row displays an error message informing you that, "This issue cannot be opened because it doesn't really exist".

There are two ways to deal with unaffiliated changes: short-term and long-term. If you are working under a deadline and just need a way to deal with these files so that they don't keep you from promoting everything in a stream, you can simply right-click this row and select Send to Issue. You then can either assign these unaffiliated changes to a new issue that you create on the fly, or send them to an existing issue if an appropriate one already exists. (An “appropriate” issue might be a catch-all issue that you always use to hold miscellaneous unaffiliated changes. Or, it might be an issue that you know makes logical sense for these particular changes.)

The long-term, more correct solution is to determine why these changes are unaffiliated, and depending on how they got into this state, attempt to correct them. In this case, it would be better to examine the individual element version that is unaffiliated, and determine if different elements require different issues for resolution. For example, if a specific unaffiliated change was caused by removing an element from a change package, the correct fix could be to assign that element to a different more appropriate issue, or to revert that element’s changes altogether. (In any case, this brings up a best practice: whenever you remove an element from a change package, you should always immediately follow-up by reassigning that element to another issue, or reverting its changes.)

To examine the unaffiliated versions in detail and deal with them, you should right-click the stream and select Show Active Issues.

From the resulting display, you can right-click the unaffiliated elements, explore their history, and then take appropriate actions to correct their unaffiliated status. For example, you can use Send to Issue and then promote, or promote the files to an issue while promoting from this stream to its parent.