SCM best practices that work

Software configuration managers and consultants are often asked for sound advice on SCM best practices. Developers and developer teams often want to know how to use SCM software most advantageously. The following best practices tips have been tried and proven, directly by experienced code developers, and indirectly by their customers.

These practices can help you in your Notes/Domino development process, but they're just as valid in general enterprise development and even in the management of open source projects with hundreds or thousands of volunteer developers.

Workspaces

Workspaces are where developers build, test, and debug. A workspace should have a single purpose, such as an edit/build/test area for a single developer, or a build/test/release area for a product release.

Don't share workspaces or work outside of managed workspaces. Stay in sync with code line, and check in often. Sharing workspaces tends to confuse people, just as sharing a desk would. Furthermore, sharing workspaces compromises the SCM system's ability to track activity by user or task.

Workspaces are easy to come by, and the disk space they occupy is plentiful; so you don't have to waste time trying to conserve them.

Code lines

Code lines are approved sets of source files. Give each code line a policy, owner, and mainline.

Policy describes how to document changes being checked in, what review is needed, what testing is required, and the expectations of code line stability after check-ins. Policy is critical component of the software development process, and a code line without a policy, from an SCM point of view, is ineffective and out of control.

An example line of code is shown in Figure A below.

Branches

Branches are variants of the code line. Branch only when necessary, and don't copy when you mean to branch.

Every branch creates more work -- more builds, more code line propagation, and more source file merges. If you keep this in mind every time you consider making a branch, you may avoid unnecessary branching.

Change propagation

Getting changes from one code line to another is what change propagation is all about. Make original changes in the branch that has evolved the least since branching. Propagate early and often.

The chore of propagating file changes across branches is rarely a trivial task. The burden of change propagation can be lightened by assigning the responsibility to the engineer best prepared to resolve file conflicts.

Builds

Builds turn source files into products. Check in all original source files. Use common build tools and build often. Keep build logs and build output. The only entities in a build should be source files and their tools. Given the same source files and build tools, the resulting product should always be the same.

If you have memorized setup procedures, automate them in scripts. If you have manual setup steps, document them in build instructions. Document all tool specifications, including operating system, compilers, include files, link libraries, make programs, and executable paths.

Final thoughts for this week

Best practices in SCM, like best practices in anything else, always seem obvious once implemented. The practices we've discussed work well if you use them. Next time in our series on SCM, we will discuss version control, auditing, and reporting.