The document discusses convergence and divergence of branches in source code management. It explains that some branches are meant to converge as work is completed, while others diverge for purposes like back-porting or customization. Three-way file merging compares a source, target, and base version, but the choice of base impacts whether changes are merged or divergence is preserved. The "merge down, copy up" method can be used to purposefully converge branches by copying changes in the correct direction.

1. Convergence vs. Divergence Purposeful Merging with Perforce Laura Wingerd  Perforce Software  www.perforce.com

2. Overview Background Branching and merging 3-way file merging Convergence vs. divergence Some branches should converge, some should diverge Merging for convergence is not the same as merging for divergence Purposeful merging How to get the merge result you want

3. Branching... DevX Main Rel 2 Rel 1 DevY DevZ

4. Branches over time... Some branches converge, some branches diverge 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

5. Branches diverge when… back-porting to release lines release lines always diverge from trunk cherry-picking e.g., hunt-and-peck feature packaging branching for customization e.g., per-customer, per-platform, etc. trading changes between developers e.g., boilerplates, code snippets

6. Branches converge when... development tasks are completed i.e., delivering completed work from dev line to mainline isolated development projects are rejoined delivering private branch work into a shared branch distributed development is reconciled developers working in separate repositories

7. Merging files Although we speak of “merging branches”... ...merging takes place between individual pairs of source and target files

8. 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

9. 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 MERGED TARGET SOURCE BASE

10. The essence of a three-way merge A4 B5 C3 D2 E6 A4 B5 C4 D4 E7 A4 B6 C3 D3 E7 A4 B6 C4 ? E7 MERGED BASE SOURCE TARGET

11. Three-way file merge tools vary... Granularity Conflict resolution File formats Syntax awareness

12. 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=&quot;create_gizmo&quot;> <title> The 'Create Gizmo' dialog </title> <graphic fileref=&quot;img/cg.gif&quot;/> </figure>

13. 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

14. The effect of base selection SOURCE TARGET A1 B1 C1 A1 ? ? X Y Z A1 B2 C1 A1 B2 C2 A1 B2 C1 A1 B3 C1 A1 B3 C2 A1 B3 C4 A1 B4 C4 A1 B3 C3 A2 B3 C4 A2 B3 C1 A1 ? ? A1 ? ? A3 B4 C4 A1 B4 C3 A3 B3 C4 A3 B4 ? A3 B3 C3 A3 B4 C3 A1 B4 C3 A3 B3 C4 A1 B3 C3 A3 B4 C4 ? B4 C3 ? B4 ? A3 B4 ? A3 ? ?

15. Base selection through the ages X Y Z SOURCE TARGET

16. Arrow types and base selection X Y Z SOURCE TARGET A1 B1 C1 A1 B2 C1 A1 B2 C2 A1 B2 C1 A1 B3 C1 A1 B5 C2 A1 B4 C1 A1 B6 C2 A1 B3 C2 A1 B4 C2 A1 B6 C2 A2 B4 C1 A2 ? C2 A1 B3 C1

17. 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

18. “ Inherited” divergence A B C

19. Unintentional divergence “ Merge down, copy up” can be foiled by “ignore” arrows A B “ nothing to integrate” C D An “ignore” arrow is not the same as backing out a change

20. The effect of “edit” arrows C D A B Change propagation is assured, but convergence is not guaranteed

21. Guaranteeing convergence “ Merge down, copy up” COPY

22. Assuring a correct copy The recipe: p4 integ –n [target] [source] p4 integ –f [source] [target] p4 resolve –at p4 diff –sr | p4 –x - revert p4 integ [source] [target] p4 resolve –at p4 submit

23. 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.

24. Convergence vs. Divergence Purposeful Merging with Perforce Laura Wingerd  Perforce Software  www.perforce.com