Convergence vs. Divergence

Purposeful Merging with PerforceLaura Wingerd • Perforce Software • www.perforce.com

Overview

BackgroundBranching and merging 3-way file merging

Convergence vs. divergenceSome branches should converge, some should divergeMerging for convergence is not the same as merging for

divergence

Purposeful mergingHow to get the merge result you want

Branching...

DevX

Main

Rel 2

Rel 1

DevY

DevZ

Branches over time...

Main

Rel1

Main

Rel1

Main

DevX

Rel1

Main

DevX

DevY

Rel1

Main

DevX DevY

DevZ

Rel1

Main

Rel2

DevX

DevY

DevZ

Rel1

Main

Rel2

DevX

DevZ

Rel1

Main

Rel2

DevX

DevZ

Rel1

Main

Rel2

DevX

DevZ

Rel1

Main

Rel2

DevX

DevZ

Rel1

Main

Rel2

DevX

DevZ

Some branches converge, some branches diverge

Branches diverge when…

back-porting to release lines release lines always diverge from trunk

cherry-pickinge.g., hunt-and-peck feature packaging

branching for customization e.g., per-customer, per-platform, etc.

trading changes between developerse.g., boilerplates, code snippets

Branches converge when...

development tasks are completedi.e., delivering completed work from dev line to

mainline

isolated development projects are rejoineddelivering private branch work into a shared

branch

distributed development is reconcileddevelopers working in separate repositories

Merging files

Although we speak of “merging branches”...

...merging takes place between individual pairs of

source and target files

Integration history “arrows”

Integration history records source-to-target relationships between file revisions

Perforce uses integration history to determine: which source revisions still need to be integrated to target

the revision that will be used as the base for a three-way merge from source to target

Three-way file merging

A source file version and target file version are merged with reference to a base file version

The merged result is a consequence of:merge tool capabilities, and... base selection

MERGEDTARGET

SOURCEBASE

The essence of a three-way merge

A4B5C3D2E6

A4B5C4D4E7

A4B6C3D3E7

A4B6C4?E7

MERGED

BASE

SOURCE

TARGET

Three-way file merge tools vary...

Granularity

Conflict resolution

File formats

Syntax awareness

Perforce’s merge tools

File formats: text

Syntax awareness: none

Granularity: line

Conflict resolution: “diligent”

Does more auto-resolving

Leaves fewer conflicts to be resolved manually

<figure id="create_gizmo"> <title> The 'Create Gizmo' dialog </title> <graphic fileref="img/cg.gif"/></figure>

What makes a good merge base?

SOURCE

A base with “qualifying history” – i.e., whose complete history is in the history of both source and target...

... and a base with lots of history – i.e., whose history has as much in common with both the source’s history and the target’s history as possible

X

Y

TARGET

Z

The effect of base selection

SOURCE

TARGET

A1B1C1

A1??

X

Y

ZA1B2C1

A1B2C2

A1B2C1

A1B3C1

A1B3C2

A1B3C4

A1B4C4

A1B3C3

A2B3C4

A2B3C1

A1??

A1??

A3B4C4

A1B4C3

A3B3C4

A3B4?

A3B3C3

A3B4C3

A1B4C3

A3B3C4

A1B3C3

A3B4C4

?B4C3

?B4?

A3B4?

A3??

Base selection through the ages

X

Y

Z

SOURCE

TARGET

Arrow types and base selection

X

Y

Z

SOURCE

TARGET

A1B1C1

A1B2C1

A1B2C2

A1B2C1

A1B3C1

A1B5C2

A1B4C1

A1B6C2

A1B3C2

A1B4C2

A1B6C2

A2B4C1

A2?C2A1

B3C1

Preserving divergence

Continuous, incremental merging preserves divergence

Cherry-picking before mass merging does not preserve divergence

After-the-fact, incremental merging preserves divergence

A

B

C

D

E

F

“Inherited” divergence

A

B

C

Unintentional divergence

A

B

“nothing to integrate”C

D

“Merge down, copy up” can be foiled by “ignore” arrows

An “ignore” arrow is not the same as backing out a change

The effect of “edit” arrows

C

D

A

B

Change propagation is assured, but convergence is not guaranteed

Guaranteeing convergence

“Merge down, copy up”

COPY

Assuring a correct copy

The recipe:

1. p4 integ –n [target] [source]

2. p4 integ –f [source] [target]

3. p4 resolve –at

4. p4 diff –sr | p4 –x - revert

5. p4 integ [source] [target]

6. p4 resolve –at

7. p4 submit

In a nutshell:

Some branches diverge, some branches converge.

With three-way merging, base selection determines divergence or convergence.

As of Rel 2006.1, Perforce’s base selection accommodates both convergence and divergence nicely, but is biased toward preserving divergence

The “merge down, copy up” method achieves convergence between branches – as long as you’re copying branches correctly.

Convergence vs. Divergence

Purposeful Merging with PerforceLaura Wingerd • Perforce Software • www.perforce.com