Processes and Tools for Effective Merging

Merge: The word sends many folks running for cover. After all, it's mind-numbing to stare at hundreds of pending merges, slowly working through them. Eyes glaze over, sanity flees, the zombies are knocking …

Oh, wait. This isn't a B-grade fright flick. Yet merge is real, and for too many, it is something to dread. Linus Torvalds has said that merge is a key issue. One of my contacts was even more blunt, saying, "With [a popular open source tool] branching is easy, but merge is hell."

It needn't be that way. Merge can be manageable, routine, and even easy with good planning and tool support. Our premise is that effective merging requires effective practices supported by good tools. We discuss best practices and tool requirements for effective merging.

Why Merge

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. We minimize costs using best practices for efficient merging.

What Is Merging

Before describing best practices, let's define what it means to merge. Merge is taking two branches of a project and combining their changes. This has three parts: Identifying what's changed, resolving any conflicts, and applying the changes. Changes may be to any of the file attributes (name, directory, existence, modes, content), including multiple attributes. When the same attribute of the same file is changed in both branches of a project, we have a conflict (unless the attribute happens to be changed identically in both branches).

Conflicts can be resolved by selecting one change and discarding the other, or combining them in some form. The most complex attribute to combine is file content and is typically the focus of merging discussions. However, efficiently identifying and applying branch changes are equally key for effective merging.

Merge Frequently and Plan Ahead

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. With proper tool support, frequent merging can become routine and take just moments to perform.

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, a project 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 Should Merge

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 to Merge

A key practice of effective merging is to first merge into 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. It also means that all conflicts are resolved in the branch, which makes the promote to the parent branch operation fast and conflict free.

Tool Support for Merge

Another key to effective project branch merging is a supportive version control solution. A good solution will allow you to easily select project branches to compare, quickly identify changes between branches, identify and guide you in resolving any conflicts, and then apply the selected changes for you. And will do so in an easy to use, easy to understand what you are doing way. In less sophisticated tools, identifying, resolving and applying are all left to the Version Control Engineer, who must write scripts, decipher arcane syntax, etc. Yet doing this manually, or even a file at a time in a script, is simply too difficult or too slow to do frequently (remember, frequent is good) or be used by most developers.

Many tools exist to resolve individual file content merge conflicts. Most such 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 two file merge tools and supports integrating additional tools. See our 3rd party merge tool write-up for more information. Other attribute conflicts are resolved directly in SnapshotCM.

Summary

Effective merging, implemented using effective practices and tools, helps you achieve the benefits of parallel development while minimizing the costs. SnapshotCM facilitates this by automating the identification of changes, guiding the user through the items requiring conflict merge resolution, and then applying selected changes. The visual branching, branch comparison and automated merges make frequent merging simple and fast enough for all development engineers to include in their normal development process. In SnapshotCM, it's the worries that flee as project merging becomes routine, simple, and even easy.

How does your current solution compare? SnapshotCM delivers a visual environment where project-level branching and merging is simple, fast and effective. Many of our customers have dozens or even hundreds of branches and releases. They all rely on SnapshotCM to keep it simple for them. Check us out by taking advantage of our free evaluation. Go to http://www.truebluesoftware.com/ for all the details.