Creating a New Change Package Entry
Modifying Existing Change Package Entries
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.
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 ...
was originally created in another workspace [example 1] [example 2]
If patching from version wheat_dvt_john/4, AccuRev determines that John's "recent changes" to this element started with version wheat_mnt_john/1. (John used Send to Workspace to bring this "mnt" version into his "dvt" workspace.)
If patching from version wheat_dvt_mary/5, AccuRev determines that Mary's "recent changes" to this element started with version wheat_dvt_john/14. (John created that version and promoted it to backing stream wheat_dvt. Mary brought the version into her workspace with an update.)
... or ...
was created in the same workspace, then was promoted to the backing stream [example]
If patching from version wheat_dvt_mary/14, AccuRev determines that Mary's "recent changes" to this element started with version wheat_dvt_mary/11. (Mary created that version -- maybe for the same development task, but maybe not -- and promoted it to backing stream wheat_dvt. Then she continued working on the element.)
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):
Patches involve real versions, not virtual versions
AccuRev's patch facility involves working with the contents of text files. And AccuRev records changes to files' contents as real versions A version of an element, created in some user’s workspace, recording a change to the contents and/or pathname of the element. See version, virtual version. in workspaces. Accordingly, AccuRev only uses real versions in its patch manipulations. If you specify a virtual version In a dynamic stream, a version of an element, created by the Promote command, which serves as an alias for (reference to) a previously created real version. In a workspace stream, a version created by the Send to Workspace or Anchor command, referring to the real version that the command "checked out". in some dynamic stream as the "patch from" version, AccuRev automatically uses the real version for which the virtual version is an alias.
What it means to be "between" the head and basis versions
In the simplest case, a patch's head version was derived from its basis version by a series of Keep commands (and maybe a Rename). In this case, it's easy to determine the set of versions that are between the head and basis versions. But what if one or more of the versions was created with Merge? Here's an example:
What if we "patch from" version wheat_dvt_john/42? The basis version corresponding to this head version is the most recent one created in another workspace and brought into workspace wheat_dvt_john by an update -- that is, version wheat_dvt_mary/52. What versions are "between" these two versions? AccuRev determines the answer by finding this set difference:
In this case, the difference between the two subsets of the element's version graph consists of eight versions, from two different workspaces.
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.
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]
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.
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.
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.)
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.
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:
Case 1: [B,H] + [H,X] (simple extension of a change package entry)
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 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 head 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.) On the other hand, it's probably OK to include the entire, uninterrupted series of versions [B,X] in your change set -- this includes both your original changes and your new changes (and, harmlessly, your colleague's changes, too).
Accordingly, AccuRev prompts you to approve this "spanning the gap" between the two change set entries, in order to create a single, combined entry.
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 (the basis version must be an ancestor of the head version).
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.
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.
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.
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:
somebody did a Promote By File without specifying an issue
somebody removed a file version from a change package (either intentionally or accidentally)
somebody patched a Change Package entry into a Workspace via the Change Palette (Path to a Tracking Issue)
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.