Structure of a Change Package

A change package is a collection of element versions; for example:

version kestrel_dvt_jjp/13 of element /./src/brass.c
version kestrel_dvt_jjp/14 of element /./src/brass.h
version kestrel_dvt_jjp/16 of element /./src/commands.c

A change package can contain entries for any number of elements.

Elements can have multiple entries showing segments -- versions between a head and a basis representing promotion(s) against different issues while this issue has been active. (Elements with such multi-segments are shown collapsed by default, and can be expanded by clicking the plus (+) icon.)

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.

The basic idea is that this set (or “package”) of versions contains all the changes required to implement a certain development project. But we need to refine this idea. Consider that version 14 of brass.h probably contains more than just the changes for that development project. For example:

•	Versions 1-7 might have been created years ago, when the product was first developed

•	Versions 8 and 9 might have been minor tweaks, performed last month

•	Versions 10-14 are the only versions with changes for the development project in question

So we need a way to express the idea that only the “recent changes” to brass.h, those in versions 10-14, are to be included in the change package. AccuRev accomplishes this by defining each change package entry using two versions: a user-specified head version and an older, automatically-determined basis version.

Note: As of AccuRev 6.0 and the introduction of "multi-segments", users can also specify basis versions under certain circumstances.

The “recent changes” to be included in the change package were made by starting with the basis version (version 9 in this example) and performing a Keep on one or more new versions (versions 10, 11, 12, 13, and 14 in this example).

In the AccuRev GUI, the head version of a change package entry is usually identified simply as the “Version”.

Note: Patch uses the same “recent changes” analysis to determine which changes in the “from” version are to be incorporated into the “to” version.

The AccuWork issue-management facility provides a logical place for keeping track of development activities for brass.h. Each task -- fixing a bug, creating a new feature, etc. -- is tracked by a particular AccuWork issue record. So AccuRev uses using issue records to implement change packages.

Each issue record includes a Changes section that acts as an “accumulator” for versions’ changes. Here’s how the above example of a change package would appear in an issue record’s form:

This change package has entries for three elements:

•

brass.c: The basis version, 15/10 was created in the user’s own workspace. This indicates that the user promoted 15/10 to the backing stream. AccuRev assumes that this change was for another task, not the one covered by this issue record. Then, the user turned his attention to the current task, creating additional versions up to and including 15/13, the head version.

•

chap03.doc: This change began when the user updated his workspace, bringing in version 4/7 of the element (which had originally been created in another workspace, then was promoted to the backing stream). Then, the user created one or more versions in his own workspace, up to and including version 15/11, the head version.

•	tools.readme: Similarly, this change began when the user updated his workspace, bringing in version 12/3, originally created in another workspace. The user created one or more versions in his workspace, ending with version 15/9, the head version.

But what happens if these files get changed again for a new release, and one of the files also gets changed in the meantime by another developer for a support issue? Fast-forward a year or so:

The change package for this new issue now includes multiple entries for one of the files, due to the introduction of multi-segments -- the ability of AccuRev change packages to track and correctly handle versions that are not necessarily related to the current changes.

•	chap03.doc: This change is basic -- the previously promoted version was updated and then promoted.

•	tools.readme: Similarly, this file was updated from its backed version and promoted.

•	brass.c: This file starts to get interesting -- it was updated and promoted against a different issue prior to being promoted for the current issue. Each set of versions between the basis and head version are recognized and treated as a separate segment.

Note: If you used AccuRev and AccuWork prior to Release 6.0, you needed to follow processes that prevented this situation, such as promoting a file only against a single issue at a time. AccuRev now keeps track of such promotions automatically through the use of multi-segments. You and your colleagues can work on the same files for different issues at the same time (merging as necessary), and AccuRev keeps track of the change package records for you.

Creating a New Change Package Entry

AccuRev records change package entries automatically, whenever Promote is invoked in a workspace. For example, suppose issue record #3 represents a particular bug (and its fix). Whenever a developer promotes one or more versions whose changes address that bug, he specifies issue #3 at a prompt. AccuRev automatically creates a change package entry in issue #3 for each promoted version.

Also, you can manually add entries to a change package: right-click a version in the File Browser, Version Browser, or History Browser, and then select Send to Issue from the context menu. The selected version becomes the head version of the change package entry. AccuRev automatically determines the corresponding basis version. As the examples above suggest, AccuRev uses an algorithm that determines the set of “recent changes” to the element, made in a single workspace.

In the Version Browser, a variation of this operation, Send to Issue (specifying basis), enables you to pick the basis version, rather than allowing AccuRev to determine it automatically.

You can also invoke Send to Issue on the Changes tab of an issue record. This copies an existing change package entry to a different change package (issue record).

Also, with the introduction of “multi-segments” in AccuRev 6.0, there are certain other circumstances in which users can specify basis versions.

Modifying Existing Change Package Entries

When you want to create a change package entry for a particular element, but an entry for that element already exists in the change package, AccuRev attempts to combine the new entry with the existing one. This produces an updated entry that includes all the changes. AccuRev always attempts to coelesce versions that are contiguous. For example, if version 3, 4, and 5 are combined with versions 6 and 7, they will be coalesced to versions 3 through 7. However, if version 3, 4, 5 are combined with versions 8 and 9, while versions 6 and 7 belong to a different change package, 3, 4, and 5 will be recorded as one segment in the change package, while versions 8 and 9 will be added as a separate segment.

Change Packages "In" Streams

As the versions in a change package are promoted up the stream hierarchy, the change package itself implicitly moves up the hierarchy, also. Roughly speaking, a change package has risen to a certain level if all its entries have risen to that level. More precisely, the change package entry for an element is said to be "in" a particular stream if the element's version in the stream is -- or is a descendent of -- the head version.

The reason that the descendant of the head version qualifies is that AccuRev assumes that changes made to an element remain in that element as subsequent versions are created. Suppose a change package entry consists of versions 13/4, 13/5, and 13/6 of some element. Another user then brings version 13/6 into her workspace with an Update, and creates descendent version 49/2. It's fair to say that the change package entry is "in" her workspace, and in any stream to which version 49/2 is promoted.

And the reason that the head (but not the basis) version is considered is that the basis version of a change package entry is always an ancestor of the head version. AccuRev assumes that changes that were present in the ancestor version remain in the later version.

In summary:

•	A change package is said to be "completely in" a particular stream if all of its entries are "in".

•	A change package is said to be "partially in" a particular stream if some -- but not all -- of its entries are "in". See Incomplete Change Packages.

•	A change package is said to be "active" in a particular stream if at least one of its head versions is in the stream’s default group.