How Changes Migrate Through the Stream Hierarchy

AccuRev provides configuration-management capabilities that are sophisticated and robust, without sacrificing ease of use. What’s the secret? One main reason is that AccuRev sees the development environment in the same way as a typical development team:

•	Many development tasks are active concurrently, all using the same source base.

•	Tasks are often interrelated; they must share their changes with each other (“integration”) and weed out inconsistencies; some tasks cannot be completed until one or more others have been completed.

•	Most tasks are accomplished by making changes to relatively few files.

•	A task is completed by “delivering” a set of changes to another task. For example, a development task might deliver its changes to an integration task, or to a testing task.

•	A developer’s next task may involve changing a completely different set of files from the previous task.

AccuRev streams neatly model all these aspects of development tasks. The (relatively few) files that a developer changes for a task become active in a particular stream. Typically, this occurs when the developer records new versions of the files. To complete the task, or to mark an intermediate milestone, the developer delivers the changes to the parent stream, using the promote command. The files become active in the parent stream, and inactive (not under active development) in the child stream.

In a multiple-level stream hierarchy, several promotions are required to propagate a set of changes all the way to the top level. Each promotion causes the file(s) to become active in the “to” stream, and inactive in the “from” stream.

AccuRev terminology: the set of elements (files and directories) that are currently active in a particular stream constitute the default group of that stream. When an element is active within the stream, it is considered a member of that stream.

You may have gotten the impression that a given file can be active in only one stream at a time. Not so — that would mean only one development task at a time could be actively working on the file. AccuRev allows each file to be active in any number of streams — even all of the streams at once. Typically, though, a file is active in just a few streams at any particular moment.

The diagram below uses contrasting colors to show how a particular file might be active in four different streams. That is, four different versions of the same file are in use at the same time, for various development tasks.

Inheriting Versions From Higher-Level Streams

What about the other streams? Each stream in the hierarchy contains some version of the file; if a file is not active in a particular stream, the stream automatically inherits an active version from a higher-level stream. The diagram below shows how the four active versions fill out the entire stream hierarchy:

This scheme makes it easy for an organization to manage many development tasks concurrently, each with its own software configuration in a separate stream. As changes are made for certain tasks, AccuRev takes care of automatically applying the changes to the software configurations used by other subsidiary tasks — except for the tasks that are actively working on the same file(s). Just a few promote operations can effectively propagate versions to tens or even hundreds of other streams.

Pass-Through Streams

AccuRev features a special kind of stream, called a pass-through stream. A version that is promoted to such a stream automatically passes through to the parent stream. The file doesn’t become active in the pass-through stream; it does become active in the parent of the pass-through stream.

Pass-through streams are useful for grouping lower-level streams. (Most commonly, the streams to be grouped are ones built into user workspaces. For a full discussion of workspaces, see AccuRev Workspaces and Reference Trees.) For example, suppose a “swat team” of four programmers often moves from project to project. AccuRev accomplishes the task of moving a programmer from Project A to Project B by reparenting the programmer’s personal stream: making it a child of the Project-B stream instead of the Project-A stream.

Reparenting all four programmers’ personal streams from the Project-A stream to the Project-B stream requires four separate operations. But suppose the programmers’ streams were all children of the same pass-through stream; moving the team to a different project requires just a single operation: reparenting the pass-through stream.

The intermediate stream level doesn’t impose any extra day-to-day work on the programmers. The versions they promote automatically pass through the intermediate stream to the project stream.

The Include/Exclude and Cross-Link Facilities

AccuRev has an advanced include/exclude facility, which vastly increases the flexibility of a depot’s stream hierarchy. You can configure any dynamic stream (or workspace) to include just some, not all, of the elements from its parent stream; the subhierarchy below the stream inherits this configuration. This facility makes it easy to logically partition a source tree, so that different development projects can work on different parts of the source code, and so that different development groups cannot even see each other’s work.

You use include and exclude rules to specify which elements are included from the parent stream.

•	An include rule can specify an individual file, an individual directory’s contents, or the contents of an entire directory tree.

•	An exclude rule can specify an individual file or an entire directory tree.

•	Rules are inherited by lower-level streams and workspaces, in much the same way that versions are inherited.

•	Rules at lower levels of the directory hierarchy can refine rules at a higher level. For example, a graphic artist might add a rule to exclude everything below the directory src, but then add another rule to include the single subdirectory src/gui/images/icons.

•	An include rule can implement a cross-link, specifying a different backing stream for an individual element or an entire subtree. In effect, this enables different elements to have different stream hierarchies, even though they are in the same depot.

In any dynamic stream or workspace, you can also change the backing stream of individual elements or entire subtrees of elements (termed cross-linking). This provides a way to make the stream hierarchy look different for different elements.