Patches and Change Packages

Structure of a Patch

Patch Display

Structure of a Change Package

Change Package Display

Creating a New Change Package Entry

Modifying Existing Change Package Entries

A Little Bit of Notation

Three Ways to Modify a Change Package Entry

Change package -- part of an issue record, or just associated with it?

A patch is a set of versions of a text-file element, whose changes have been incorporated into another version of the element with the Patch (or Patch From) command. Informally, a patch consists of one user's "recent changes" to the element. The patch facility was designed to easily transfer to another development context the set of changes that were made to an element for a particular development task.

A change package contains a set of entries, each of which (usually) has the same form as a patch. But change package entries can be modified (added to) after they are first created. Such modified entries don't fit the "recent changes" description; rather, a change package entry can act like an accumulator, recording all the changes made to the element to fulfill a particular development task. The change package facility was designed to track exactly what element-by-element changes go into the bugfix or feature that the issue record describes.

Structure of a Patch

The Patch command creates a new version in a workspace. This version is termed the head version of the patch. AccuRev automatically determines a corresponding basis version by scanning backward through the element’s ancestry The entire set of versions of an element. See version graph.. The basis version is the most recent version that ...

... or ...

The patch consists of all the versions between the head version and the basis version. (The head version is included in the patch; the basis version isn't.)

Notes (click to view):

Patch Display

In the Version Browser, a version created by Patch is connected to the "patch from" version with a dashed red line. Selecting this version highlights the versions in the patch.

Structure of a Change Package

Each issue record (AccuWork) A data record, consisting of values of data fields, stored in an issue database. in an AccuWork issue database (AccuWork) A set of issue records, each of which implements a bug report, feature description, etc. Each depot can have its own issue database. Each issue database has its own schema. includes its own change package. A change package can contain entries for any number of elements -- but only one entry per element. The elements must belong to the same depot as the issue database.

Each change package entry is similar to a patch -- it consists of all the element's versions between a designated head version and basis version. This is a more general structure, because there is no "one user's recent changes" restriction to the scope of versions. The only restriction to is that the basis version be an ancestor In the version graph of an element, version A is an ancestor of version B is there is a direct line of descent (possibly including merges) from A to B. See predecessor (or direct ancestor). 'A is an ancestor of B' is equivalent to 'B is a descendant of A'. of the head version -- so that the set of "between" versions is well-defined. [examples]

 

Change Package Display

In the Changes subtab of an issue record's edit form (AccuWork) A fill-in-the-blanks form for displaying and changing the field values of issue records. (and equivalently, in a Stream Issues tab), a change package is displayed in a table, each row showing one change package entry. Example:

As with a patch, each change package entry has a head version (Version column) and a basis version.

Creating a New Change Package Entry

Typically, a new change package entry is exactly like a patch -- the Send to Issue command and the change package-level integration between AccuRev and AccuWork create an entry whose basis version is automatically selected in the same way as the Patch command. When the entry is later modified, it assumes the more general structure.

You can create a new change package entry with the more general structure using the "specifying basis" variant of the Send to Issue command.

Modifying Existing Change Package Entries

Change packages are designed to track ongoing changes to elements, not just a single set of changes. This means there will be times when you want to add a change package entry for a particular element, but an entry for that element already exists in the change package. In such situations, AccuWork attempts to combine the new entry with the existing one, producing an updated entry that includes all the changes. (Recall that there can be at most one entry for a given element in a given change package.)

A Little Bit of Notation

To help explain how AccuWork 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.

Three Ways to Modify a Change Package Entry

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

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.

Change package -- part of an issue record, or just associated with it?

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 there is no need to 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 don't participate in the AccuWork's issue-history capability. Modifications to a change package don't appear in the Issue History subtab of an edit form (although you can use the Change Package History feature described above). And if you use this subtab to view an "old" version of an issue record, the Changes subtab still displays the current contents of the change package, not the "old" contents.

Given this behavior, you may want to think of a change package as being associated with an issue record, rather than being part of it.

 

Unaffiliated Changes ("Dark Matter")

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. Or somebody might decide to promote a file in a backing stream, without associating it with an issue. If such element versions are not associated with any issue, they are considered unaffiliated, or (more colorfully) "dark matter". Such element versions can lead to confusion, AccuRev provides a way to view unaffiliated changes in the GUI.

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 table layout includes the ShortDescription column, you will also see "UNAFFILIATED CHANGES" in the row. 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, for example, just Promote by File without associating the files with an issue. However, this is just a temporary fix, and you are just perpetuating the problem and pushing it further up your streams.

 

The long-term, correct solution is to determine why these changes are unaffiliated, and depending on how they got into this state, attempt to correct them. Typically there are three ways that an unaffiliated change may occur:

Once you have committed to working with change packages, you should never do Promote By File operations without associating the files with an issue. These can result not only in unaffiliated changes, but they can also cause incomplete change packages which are another source of confusion (see the  "Incomplete Change Packages" chapter of the AccuRev Technical Notes manual for more information).

 

In any case, the best way to proceed is to associate the unaffiliated change with an issue, either by using Send to Issue for an existing issue, or by creating a new issue to handle this specific change.

 

To examine the unaffiliated versions in detail and deal with them, you should right-click the stream and click 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.