RFC: merge tracking in the svnbook

From: Ben Collins-Sussman <sussman_at_red-bean.com>
Date: 2007-11-26 16:59:14 CET

Folks, having been officially "not full time" on svn for the last two
years, I have the ... interesting ... task of essentially doing a
total rewrite of the merging chapter of the svnbook. What's
interesting about it is that it's the first time I'll be documenting
something that I don't intimately know from the inside out -- I've
only been marginally following the evolution of "basic merge
tracking", and so I'm approaching the whole thing as a black-box.

In any case, I've rewriten the outline for the merging chapter below.
I wanted to share it with this list to get feedback. Have I left out
major aspects of the new merging feature?

Document Basic Merge-Tracking as 'black box'.

Chapter 4. Branching and Merging

What's a Branch? --> layman's explanation of a branch
--> TODO: why branches are important for software devel

Using Branches --> introduce harry/sally feature-branch scenario

        Creating a Branch -> shows wc->wc copy. TODO: stop showing that!
                           -> sidebar on 'cheap copies'
        Working with Your Branch -> svn co newbranch
                                  -> make changes, examine logs
        The Key Concepts Behind Branches -> svn doesn't know what a branch is
                                          -> TODO: stress that branch
                                             location doesn't matter
                                          -> TODO: only discoverable
                                             by examining history and
                                             seeing copy
    Basic Merging (NEW)

        Merging branches to each other
            -> show how to repeatedly merge trunk to the example feature branch
            -> show how to merge feature branch to trunk when done

        Basic Merge Tracking
            -> set expectations appropriately
            -> only works with both 1.5 server and client!
            -> Previewing Merges -> shows revert, TODO: add --dry-run
            -> Merge Conflicts -> TODO: explain how conflicts can
                                            block successive ranges of merges

Advanced Merging (NEW)

        Explain svn:mergeinfo prop & 'svn mergeinfo'.
        Copying Specific Changes -> shows how to port 1 changelist
        The Key Concept Behind Merging -> explains 'detailed' merge syntax
        Undoing Changes -> also show 'svn cat' method, link from ch02?
        Resurrecting Deleted Items
        Blocking changesets -> demonstrate --record-only
        Enhanced 'log' and 'blame' -> demonstrate -g switch
        Noticing or Ignoring Ancestry -> is this still relevant?
        Merges and Moves -> describe new 1.5 behavior.
        Blocking pre-1.5 clients -> what's our method for this?

    Common Branching Patterns
        Release Branches
        Feature Branches

Traversing Branches -> TODO: rename Accessing Branches Easily