The 5 W's of Effective Merging

Who, What, When, Where, and Why

Effective merging requires effective practices. We discuss best practices for avoiding unnecessary merges, simplifying merges when necessary, and for handling the hardest merges.

WHY The first question we need to ask is "Why merge?" After all, global strict locking can force all changes to be done sequentially so that merging is unnecessary. But what does it mean to do global strict locking? It means we never allow branching and never allow two people to work on the same code at the same time. It means no parallel development, no patches to old bits. For most of us then, the reason we need to merge is because we choose actions today that lead to merging tomorrow.

Examples where merging is eventually needed include creating a patch to an existing release while also working on the next release, where we want to merge patch changes into on-going work; working on multiple features at the same time, where we want to merge both features into the same release; working on the next generation solution while finishing up the existing release, where we want to insure all release changes are incorporated into the next release; and so on. All are common scenarios for a productive software development team.

Merging then is the result of doing the things which lead to merging. We judge that the benefits exceed the costs. Still, it behooves us to keep those costs to a minimum. Below we discuss best practices for efficient merging.

WHAT Before going into those best practices, let's define what it means to merge. Merge is taking two branch revisions of a file that have a common ancestor revision and combining their changes (relative to that ancestor) into a single revision. Each branch revision was created by modifying the ancestor revision in some way and checking in the result. The changes may be to any of the file attributes (name, directory, existence, modes, content), including multiple attributes. When the same attribute is changed in both branch revisions, we have a conflict (unless the attribute happens to be changed identically in both branches).

Conflicts can be resolved by selecting one or other of the attributes, or combining them in some form. The most complex attribute to merge is file content and is typically the focus of merging discussions.

WHEN A key practice for effective merging is to merge frequently. Don't let your branch get far removed from your parent branch. Several frequent merges are easier and less error prone than a few big merges. Consider that if you change a file after someone else has done a check in, but you neglected to merge from their branch first, then you are headed toward an unnecessary content merge. Frequent merging can reduce the number of conflicts, simplify the merge tasks and reduce the risk of parallel development.

Another key practice for effective merging is to plan feature additions by the area of code which is affected and to compartmentalize changes as much as practical. For example, if two changes need to be made to the same area of code, do them one at a time rather than having two users do them in parallel. Doing them serially avoids the need to merge the separate changes later.

A third key practice for effective merging is to avoid reformatting source files in a parallel development context. While the best tools can ignore minor white space changes, wholesale reordering of functions or declarations can simply overwhelm a merge tool. The result is you will end up re-applying one set of changes by hand. If source reformatting is to be done, do it when parallel changes are not going on. One thing to keep in mind: if a change must be redone by hand, it will be much easier to redo the second time around if the context of the original change is still fresh in mind. Typically that means if it is redone by the original user and done soon after the original change.

A fourth key practice for effective merging is to avoid merging and use an alternative method to maintain parallel revisions of a file. For example, SnapshotCM has both Current and a NextGen branches. After every release, the Current branch is merged forward into the NextGen branch. This frequently results in significant merge effort. In some cases, the next generation and current versions of files are such that the two revisions can be maintained in a single version using ifdefs to keep the parallel changes straight. This alternative to parallel file revisions is not always practical or appropriate, but in some circumstances, it can be most effective.

WHO Another key practice for effective merging is to have the person doing a merge be the same person who made the change being merged. The change author is the one who best understands the change and if the merge is performed soon after the change is completed, the context of the change still will be fresh in mind. Such context is vitally important to reducing risk and cost of merging, as anyone who has done a significant merge months later will attest.

WHERE A key practice of effective merging is to do all merging in the workspace or leaf branch and only check in or promote the results after verification. To do the reverse compromises the shared branch with untested and unstable code, which can affect the rest of the team who may merge from the parent branch at any time.

HOW Content merging can be done manually or with the assistance of a merge tool. Most tools provide for an automatic merge, requesting assistance only when the same region of the original file is modified by both branches. SnapshotCM ships with automated merge tools and supports integrating 3rd party tools. See our 3rd party merge tool write-up from the June, 2005 newsletter for more information.

Effective merging,implemented using effective practices and tools, helps you achieve the benefits of parallel development while minimizing the costs. SnapshotCM also simplifies parallel development and merging with its graphical branching, branch comparison, and automated merge functionality.

To see SnapshotCM in operation, get a free SnapshotCM evaluation copy at http://www.truebluesoftware.com/ or contact us for a demo.