12.5 History of Multiple Resources

One of the most complex parts of versioning with multiple files is looking back in time. Imagine that a mistake was made recently in the development of a software project and hasn't been fixed yet. The build team wants to be able to rebuild the software project from a point before the error was made. Imagine that this point is called "build 148," because the build team numbers builds sequentially. How does one identify which versions of every file to use in build 148? How does one identify which points in time are interesting checkpoints?

A rather unsophisticated approach is to copy an entire versioned repository to create a checkpoint. If a project reaches Beta 1, the administrator might create a directory somewhere and copy the entire version-controlled repository or just the latest versions of each file in the repository to the Beta 1 directory. Either way, this takes up an enormous amount of space. Another drawback is that the files in the Beta 1 directory must be carefully managed so that they cannot be accidentally altered. In any case, because of the costs of this approach, the project won't likely have many such checkpoints.

Another naive approach is to use timestamps to determine checkpoints. Every version has a creationdate property. Pick the point in time for build 148, and select the last version of each file that was created before that point. However, this approach has problems because files can be moved. If a VCR is moved into the software build area of the repository from some other area of the repository, it may have a history that predates build 148, even though it was moved into the project afterward and should not be included in build 148. Another problem is that it's difficult to recall at exactly what point build 148 occurred.

The final naive approach is to use labels. After some changes have been made, an automatic process can use the LABEL method on the current version of every VCR to label this instant as "build 148." Unfortunately, while the automatic process is applying this label to all the current versions, somebody could be in the process of adding new versions on files that the process hasn't labeled yet. The resulting set of versions selected by the "build 148" label may not be consistent. Labels could still be used if the repository is locked during labeling, but this isn't ideal. Also recall that labels can be changed, thus changing the set of versions that makes up our checkpoint: We ideally want the flexibility of labeling a set of versions but also the reliability of a fixed, unchangeable checkpoint.

So far, our requirements are that a checkpoint must be unchangeable and that it archives the state of a set of resources at a point in time. This is starting to sound just like a version, only for a set of resources instead of just one resource. Perhaps if we had a different kind of container resource that captured the state of multiple resources, we could then track the version history of that set. This new container resource exists in DeltaV, and it is called a configuration. A configuration is rooted at a collection, and it includes all VCRs inside the collection. The configuration is different from the collection because it includes VCRs within subcollections too, but it does not include any other kind of resource besides VCRs.

A configuration changes when any of its VCRs change. A configuration is a VCR, too. The configuration can be checked out and checked in to create a new configuration version. A configuration version is called a baseline.

The term for the collection where the configuration is rooted is a baseline-controlled collection because all VCRs within that collection have their collective state captured in baselines.

12.5.1 Baselines

Although baselines look very complicated, the function they serve is rather simple. Baselines select one version from all the VCRs in a configuration. When the baseline is created, the current version of each VCR in the configuration is referenced in the baseline. Only one version from each VCR may be in any baseline. However, the same version may appear in many baselines (see Figure 12-8).

Figure 12-8. Baselines identify sets of versions.

Once the baseline is created, its membership never changes. VCRs that were added to the configuration after the baseline was created do not appear in the baseline. VCRs that were deleted from the configuration after the baseline was created are still represented through their version links in the baseline.

It is possible to customize the state of the VCRs in a configuration to create a baseline with specific versions of those VCRs. To do this, UPDATE VCRs as necessary so that the target version is the version that is wanted for the baseline, and then create the baseline by checking in the configuration. However, it is not possible to create a baseline that does not include every VCR in the configuration at the instant the baseline is created.

The exact mechanism by which a baseline lists a number of versions is with the aid of a baseline collection. A baseline collection may contain subcollections and VCRs, where each VCR has the same checked-in version it had when the baseline was created. It's the list of members and their target versions that is the important data in a baseline collection.

There exists one more new resource tied to baselines, the baseline history resource. A baseline history resource is just a VHR used to track baselines instead of versions. Otherwise, it behaves identically to a VHR tracking versions.

Baselines, baseline-history resources, configurations, baseline-controlled collections, and baseline collections have all been introduced rather quickly. Here's the big picture, literally (see Figure 12-9).

Figure 12-9. Baselines, configurations, and baseline history resource.

In Figure 12-9, we have one baseline-controlled collection in the main repository. It contains three VCRs. The collection was put under baseline control with the BASELINE-CONTROL method, and that request created the version-controlled configuration, the baseline-history resource, the first baseline, and the first baseline collection. Whenever the version-controlled configuration is checked out and checked in again, a new baseline and a new baseline collection are created to capture the changed state.

12.5.2 Configurations and Subconfigurations

A configuration is rooted at a collection, and normally the configuration refers to all VCRs inside that collection (recursively). However, configuration membership can be customized if subconfigurations exist. If a collection /hr has a configuration, and its subcollection /hr/recruiting also has a configuration, then the recruiting configuration is a subconfiguration of the HR configuration. The HR configuration refers only to the set of resources inside /hr that are not included in a subconfiguration (see Figure 12-10).

Figure 12-10. Resource tree showing configuration membership.

When baselines are created, each baseline only includes versions of VCRs from the configuration, not versions of VCRs from the subconfiguration (and vice versa). Each baseline has links to the subbaselines to which it is related, so it's possible to reconstruct the state of an entire repository, even when the repository is broken up into several configurations for easier management.

12.5.3 Collection Membership Versioning

Tracking the combined history of multiple resources involves a few problems that aren't solved by baselines. If a resource is added to a collection and then removed in between creating baselines, it's hard to tell that the resource ever existed in that collection. In fact, if the resource wasn't a VCR, there may be no record of its existence.

DeltaV defines version-controlled collections to solve this problem. One way to understand version-controlled collections is to compare the concept to baselines:

• Baselines are only created on request. Versions of version-controlled collections are created whenever the collection changes.

• A configuration covers a set of VCRs that are not all in the same parent collection. A version-controlled collection only keeps track of its direct children.

A version-controlled collection is much like a VCR, having a VHR and versions and changing when content and dead properties change. The content of a collection is its membership list. Every change to the collection's direct membership (every added, deleted, or renamed resource) could create a new version of the collection if autoversioning is supported. The collection can also be checked out and checked in to create new collection versions.

Figure 12-11 shows that a collection version is much the same as a regular version. It doesn't have a body or contents, however. Instead, it has a version-controlled-binding-set property that lists the name (and VHR, not shown in the diagram) of each member of the collection.

Figure 12-11. Version-controlled collection and its versions.

Version-controlled collections don't track nonversioned resources at all. That's too bad, since baselines don't track nonversioned resources, either. These can slip through the cracks in a versioning system, untracked, untrackable, leaving no mark that they ever existed in any baseline or collection version. Serious versioning systems generally make every resource version-controlled.

Version-controlled collections are briefly specified in DeltaV but are still very complex because of the many interactions.

12.5.4 Working Collections

Just as a working resource exists for a regular VCR, a working collection can exist for a version-controlled collection. To create a working collection, CHECKOUT a specific version of a version-controlled collection. You can make changes in the working collection, and a new collection version is only created when the working collection is checked in. Since a working collection is a kind of a working resource, the same rules that apply to a working resource apply to a working collection. For example:

• The resource type of the working resource is always the same as the resource type of the version that was checked out. For a working collection, that type is a collection.

• A working resource only exists in checked-out mode. It is destroyed when checked in, or it may be deleted. The same is true for a working collection.

A working collection contains unversioned resources and VHRs but never VCRs. Thus, resources inside a working collection cannot themselves be checked out and checked in. New resources created with MKCOL and PUT are created as unversioned resources. If a working collection is checked in while it contains nonversioned resources, the nonversioned members are converted to versioned resources.

To add a nonversioned resource to a versioned collection and keep the new resource nonversioned, a working collection can't be used, because when it is checked in, unversioned resources are converted to versioned resources. Add the new nonversioned resource to the version-controlled collection (which can be done without checking out the collection at all).

It's hard to tell if working collections are incompletely specified in DeltaV or if they are simply a complicated concept to begin with. For example, the DeltaV mailing list archives have quite a few confused questions related to moving versioned resources between version-controlled collections when the version-controlled collections are checked out to working collections. I have a terrible time understanding this part of the specification, as well as the answers on the mailing list, which leads me to believe that the feature may be particularly complex or underspecified. Here are some of the issues:

• DeltaV seems to allow MOVE of a VCR into a working collection. However, a working collection can't contain VCRs, only links to VHRs. One way to handle this MOVE would be to find the associated VHR and link that into in the working collection instead. However, VHRs have no target version. When the working collection is checked in, resulting in a moved VCR in the version-controlled collection, it's not clear what the target version of the moved resource should be.

• DeltaV seems to allow MOVE of a VHR from inside a working collection. However, VHRs cannot normally be moved, according to the definition of a VHR.

• Taking the previous two points together, there may be no way to move a resource from one working collection to another. The client could use COPY (which should work the same way as PUT) and then DELETE the source for more reliable behavior.

• If a server does allow a resource to be moved from one working collection to another, and then the first working collection is checked in and the second is deleted, the moved resource may not exist anymore. Some have argued that this is the client's fault and may result in the resource being deleted from the version-controlled collection in which it originally appeared.