High-level Best Practices
in Software Configuration Management

Laura Wingerd & Christopher Seiwald
Perforce Software


When deploying new SCM (software configuration management) tools, implementers sometimes focus on perfecting fine-grained activities, while unwittingly carrying forward poor, large-scale practices from their previous jobs or previous tools. The result is a well-executed blunder. This paper promotes some high-level best practices that reflect the authors' experiences in deploying SCM.

1. Introduction

"A tool is only as good as you use it," the saying goes. As providers of software configuration management (SCM) tools and consultants to software companies, we are often asked for sound advice on SCM best practices - that is, how to deploy SCM software to the maximum advantage. In answering these requests we have a bounty of direct and indirect SCM experience from which to draw. The direct experience comes from having been developers and codeline managers ourselves; the indirect experience comes from customer reports of successes and failures with our product (Perforce) and other SCM tools.

The table below lists six general areas of SCM deployment, and some coarse-grained best practices within each of those areas. The following chapters explain each item.

Where developers build, test, and debug.

  • Don't share workspaces.
  • Don't work outside of managed workspaces.
  • Don't use jello views.
  • Stay in sync with the codeline.
  • Check in often.

The canonical sets of source files.

  • Give each codeline a policy.
  • Give each codeline an owner.
  • Have a mainline.

Variants of the codeline.

  • Branch only when necessary.
  • Don't copy when you mean to branch.
  • Branch on incompatible policy.
  • Branch late.
  • Branch, instead of freeze.

Change Propagation
Getting changes from one codeline to another.

  • Make original changes in the branch that has evolved the least since branching.
  • Propagate early and often.
  • Get the right person to do the merge.

Turning source files into products.

  • Source + tools = product.
  • Check in all original source.
  • Segregate built objects from original source.
  • Use common build tools.
  • Build often.
  • Keep build logs and build output.

The rules for all of the above.

  • Track change packages.
  • Track change package propagations.
  • Distinguish change requests from change packages.
  • Give everything an owner.
  • Use living documents.

2. The Workspace

The workspace is where engineers edit source files, build the software components they're working on, and test and debug what they've built. Most SCM systems have some notion of a workspace; sometimes they are called "sandboxes", as in Source Integrity, or "views", as in ClearCase and Perforce. Changes to managed SCM repository files begin as changes to files in a workspace.

The best practices for workspaces include:

3. The Codeline

In this context, the codeline is the canonical set of source files required to produce your software. Typically codelines are branched, and the branches evolve into variant codelines embodying different releases. The best practices with regard to codelines are:

Figure 1: The Mainline Model
Mainline model

Figure 1 shows a mainline (called "main"), from which several release lines ("ver1", "ver2" and "ver3") and feature development lines ("projA", "projB", and "projC") have been branched. Developers work in the mainline or in a feature development line. The release lines are reserved for testing and critical fixes, and are insulated from the hubbub of development. Eventually all changes submitted to the release lines and the feature development lines get merged into the mainline.

The adverse approach is to "promote" codelines; for example, to promote a development codeline to a release codeline, and branch off a new development codeline. For example, Figure 2 shows a development codeline promoted to a release codeline ("ver1") and branched into another development codeline ("projA"). Each release codeline starts out as a development codeline, and development moves from codeline to codeline.

Figure 2: The Promotion Model
promotion model

The promotion scheme suffers from two crippling drawbacks: (1) it requires the policy of a codeline to change, which is never easy to communicate to everyone; (2) it requires developers to relocate their work in progress to another codeline, which is error-prone and time-consuming. 90% of SCM "process" is enforcing codeline promotion to compensate for the lack of a mainline.

Process is streamlined and simplified when you use a mainline model. With a mainline, contributors' workspaces and environments are stable for the duration of their tasks at hand, and no additional administrative overhead is incurred as software products move forward to maturity.

4. Branching

Branching, the creation of variant codelines from other codelines, is the most problematic area of SCM. Different SCM tools support branching in markedly different ways, and different policies require that branching be used in still more different ways. We found the following guidelines helpful when branching (and sometimes when avoiding branching):

5. Change Propagation

Once you have branched codelines, you face the chore of propagating file changes across branches. This is rarely a trivial task, but there are some things you can do to keep it manageable.

6. Builds

A build is the business of constructing usable software from original source files. Builds are more manageable and less prone to problems when a few key practices are observed:

7. Process

It would take an entire paper, or several papers, to explore the full scope of SCM process design and implementation, and many such papers have already been written. Furthermore, your shop has specific objectives and requirements that will be reflected in the process you implement, and we do not presume to know what those are. In our experience, however, some process concepts are key to any SCM implementation:

8. Conclusion

Best practices in SCM, like best practices anywhere, always seem obvious once you've used them. The practices discussed in this paper have worked well for us, but we recognize that no single, short document can contain them all. So we have presented the practices that offer the greatest return and yet seem to be violated more often than not.

We welcome the opportunity to improve this document, and solicit both challenges to the above practices as well as the additions of new ones.

9. References

Berczuk, Steve. "Configuration Management Patterns", 1997. Available at http://www.bell-labs.com/cgi-user/OrgPatterns/OrgPatterns?ConfigurationManagementPatterns.

Compton, Stephen B, Configuration Management for Software, VNR Computer Library, Van Nostrand Reinhold, 1993.

Continuus Software Corp., "Work Area Management", Continuus/CM: Change Management for Software Development. Available at http://www.continuus.com/developers/developersACE.html.

Dart, Susan, "Spectrum of Functionality in Configuration Management Systems", Software Engineering Institute, 1990. Available at http://www.sei.cmu.edu/technology/case/scm/tech_rep/TR11_90/TOC_TR11_90.html

Jameson, Kevin, Multi Platform Code Management, O'Reilly & Associates, 1994

Linenbach, Terris, "Programmers' Canvas: A pattern for source code management" 1996. Available at http://www.rahul.net/terris/ProgrammersCanvas.htm .

Lyon, David D, Practical CM, Raven Publishing, 1997

McConnell, Steve, "Best Practices: Daily Build and Smoke Test", IEEE Software, Vol. 13, No. 4, July 1996

van der Hoek, Andre, Hall, Richard S., Heimbigner, Dennis, and Wolf, Alexander L., "Software Release Management", Proceedings of the 6th European Software Engineering Conference, Zurich, Switzerland, 1997.


1. Some sensible codeline policies: Development codeline: interim code changes may be checked in; affected components must be buildable. Release codeline: software must build and pass regression tests before check-in; check-ins limited to bug fixes; no new features or functionality may be checked in; after check-in, branch is frozen until entire QA cycle is completed. Mainline: all components must compile and link, and pass regression tests; completed, tested new features may be checked in.