Photo by Marjory Collins. Library of Congress, Prints & Photographs Division, FSA-OWI Collection, Reproduction Number: LC-USW3-009019-D.

“Morgue” of the New York Times newspaper. Clippings on every conceivable subject are filed here for a reference. Editors and writers phone in for information. New York, September 1942.

Sometimes you want to evaluate rapidly a complex change that may break the system while you maintain an Active Development Line (5). This pattern describes how to maintain local traceability without affecting global history unintentionally.

Note

How can you experiment with a complex change and benefit from the version control system without making the change public?

Some programming tasks are best done in small, retractable steps. If you are making a complex change, you may want to checkpoint an intermediate step so that you can back out of a change easily. For example, if there are a number of design choice points, you may want to explore one path and be able to back out to an earlier decision point when you see a problem with the implementation, as shown in Figure 16-1.

Figure 16-1. Each decision leads to more choices, until you pick the solution.

Your version control system provides a way of checkpointing your work and reverting to earlier states of the system. When you check something in to the active codeline, you subject every other member of your team to the changes. When you are exploring implementations, you may not want to share your choices until you have fully evaluated them. You may even decide that the change was a dead end.

If you don't want to use the version control system to track your changes and not cause other developers delay, you will have to test your changes in accordance with your codeline policy. You may also need to integrate changes so that other code works with any API changes you made. This can take an unjustifiably long time if you are just experimenting with options. If you decide to skip the tests, you will cause problems for other developers if you break the build or the built system. If you skip integrating your changes with the rest of the system, you will break the codeline. This is too much work for a change that you may throw away in an hour or a day. Figure 16-2 shows still another option; you can check in changes and revert at each step. This generates many superfluous change events for the rest of the team and enables you to retrace your changes only one step at a time.

Figure 16-2. Using the codeline for staging generates a lot of noise.

Even if you did put the effort into validating changes before checking them in, you would be cluttering the version history with changes that are not salient to the main change path. Because the version history for a component is important, it may be important to keep the version history uncluttered with insignificant changes.

You might consider just doing all the changes in your workspace and not checking in any intermediate work. If you don't check in any changes, you can't back off changes. You can take an ad hoc approach to saving the state of your work at various points in time by copying files or using some other mechanism, but then you are really creating a minimalist version control system. It's optimistic to expect to develop a mechanism that gives you the features you want reliably without investing more work than is appropriate.

You can also use private versions to test how integrating with the current state of the codeline will work with your software. You can check your changes in to your private version, then catch up with the codeline, and then easily roll back if there is a problem.

The dilemma is that you want to use the tools of your trade, including version control, to create a stable, useful codeline, but you want to do this privately.

A Private History

Note

Provide developers with a mechanism for checkpointing changes at a granularity they are comfortable with. This can be provided by a local revision control area. Only stable code sets are checked in to the project repository.

Set up developers' workspaces so that they can check in changes to a nonpublic area when they are making an appropriate change. The mechanism should allow them also to integrate their working code base with the current state of the active development line. This private repository should use the same mechanisms as the usual version control system so that the developers do not need to learn a new mechanism. This allows developers to experiment with complex changes to the code base in small steps, without breaking the codeline if an experiment goes awry. Developers can make small steps with confidence, knowing that they can abandon part of a change if it takes longer than they expect.

There are many ways to implement this. One way is to have an entire Private Workspace (6) dedicated to a task. This is appropriate when you want to experiment with a global change (for example, to an interface) and evaluate the consequences of the change to see whether they are manageable in the time you have. If your change involves only a small portion of the source tree (one Java package or one directory), you can map that part of the workspace to a “private” repository—for example, a local CVS repository or a developer-specific branch of the main repository that is not integrated with the active line. You then redirect certain check-ins to the private repository. When you are done with your work, check the files in to the main repository, either by specifying the repository or by copying files from the test workspace to your real one. Be sure to follow all the procedures in your standard codeline policy before checking the code in to the active codeline.

Some tools provide for promotion levels or stages. You can create private stages to use version control and not publish changes to the rest of the team.

It is important to make sure that developers using private versioning remember to migrate changes to the shared version control system at reasonable intervals. Although one way to implement this is to provide a separate source control repository for each developer in addition to the shared repository, this can also be implemented within the framework of the existing revision control system. If the revision control mechanism provides a means for restricting access to checked-in versions that are not yet ready for use by others, we can use the common version control system as a virtual private repository.

The important principle is to allow developers to use the version control system to checkpoint changes in a granularity that meet their needs, without any risk of the changes (which may be inconsistent) being available to anyone else.