Ben Collins-Sussman wrote:
> 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?
Ben,
I've also been out of touch and am looking at this merge tracking work from an
outsider's point of view.
> 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
Careful not to spend too much effort on this. It's an interesting and endless
topic in its own right but the part of it that is especially valuable here is
to establish some terminology and orientation for someone who is going to read
the rest of the chapter, not a complete novice.
> 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
Presumably you should also mention here "svn switch" as another valid way.
There's a section later that you can reference.
> -> 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
I don't like the section titles "Basic" and "Advanced" used like this. "Merging
branches to each other" is a demonstration of one kind of merging which happens
to be particularly simple to manage in v1.5, not the only basic kind of merging
that a user will need.
Can you split the sections along functional lines instead, or as "An example"
(the above) followed by "A complete description" (all the rest)?
> 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?
The only things in this list that I'd consider conceptually "advanced" are:
- svn:mergeinfo prop, which should be barely mentioned in the basic
sections, any further explanation of the property itself being a truly
"advanced" topic.
- blocking changes
- blocking pre-1.5 clients, which should be just a brief mention here that
it is possible and a link to a full "why and how" section in a server
administration chapter.
The others are all things that a typical user is going to need. But this is
only my subjective opinion.
> Common Branching Patterns
> Release Branches
> Feature Branches
I think it is important to go into some detail on how one can manage the
different conceptual kinds of branch. This would be our "best practice"
section: not mandatory but demonstrative.
The feature branch is one simple kind of branch: it involves merging all of the
new changes one way or the other at every stage.
The "stabilisation" or "release" branch involves merging just a few selected
changes from the trunk (or, more generally, its parent) to it, and either
selected or all changes from it to the trunk - "cherry picking".
-> show how to occasionally merge a selected change ("bug fix") from
trunk to a "release" or "stabilisation" branch
-> show how to make a temporary "holding" branch for this change if it
needs reviewing first, like in the Subversion project's own release branches.
-> show how to merge a selected changes ("bug fix") from release branch
to trunk
-> point out that a release branch does not get "finished" in the way
that a feature branch gets copied to trunk; rather it would tend to be kept
open indefinitely, and maybe eventually deleted without necessarily copying all
of its changes back to the trunk.
> Traversing Branches -> TODO: rename Accessing Branches Easily
This is the section about "svn switch". A title of "Accessing Branches Easily"
would imply to me a convenient way to refer to branches in svn commands, which
is something we might have eventually but not what this section is about.
> Tags
>
> Creating a Simple Tag
> Creating a Complex Tag
I recommend taking Tags out of the Branching and Merging chapter.
> Branch Maintenance
>
> Repository Layout
Consider taking Repository Layout out of this chapter.
> Data Lifetimes
>
> Vendor branches
>
> General Vendor Branch Management Procedure
> svn_load_dirs.pl
Vendor Branches are another common (but not quite so common) branching pattern
so should be at least mentioned under "Common Branching Patterns" above even if
the description remains in this separate section.
> Summary
>
> ---------------------------------------------------------------------
General:
Laura Wingerd (author of "Practical Perforce") has some useful concepts for
understanding branching and merging, such as the "Tofu scale" from "soft" to
"firm" branches, and "convergence" versus "divergence". These concepts help in
stating principles for managing branches, such as: "When merging down the Tofu
scale from firm to soft (release to trunk or trunk to feature), one shall
always merge all outstanding changes". Not sure of the ethics of you going and
reading that book though!
Early on in the chapter there needs to be a basic work-flow showing Merge ->
Resolve -> Submit.
There needs to be an explanatory section on Resolving Conflicts. Say how
certain changes conflict, and to what extent tree merges are treated the same
as text merges (maybe two adds of the same file conflict, whereas adds of the
same line in a file are silently resolved).
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sun Dec 9 22:37:06 2007