Re: [boost] [SVN] Repository branches/libs experiments

From: Sebastian Redl (sebastian.redl_at_[hidden])
Date: 2007-08-26 11:30:03

David Abrahams wrote:
> The built-in
> help is extremely good, and for those people who need more, the online
> book is written in terms of the command-line tool
The built-in help is good, but reference-style. The book is good, but
particularly when it comes to merging, I found its explanations to be
lacking. I needed several reads and quite a bit of experimentation to
understand how merging works.

Which is strange, because once you've understood it, it's really simple.

So, there are two common usage scenarios for merging: bringing branch
developments back into the trunk (or to another branch), and merging
specific trunk changes to a branch.

The merge command has three arguments: the old state, the new state, and
the application state. In general, usage of merge is:
1) Old state is where the changes that you want to merge are not.
2) New state is where the changes are.
3) Application state is the place you want to merge to.
The old and new states are represented by repository URLs, the
application state is a working copy.

Scenario 1: When development of a new feature on a branch is complete,
you'll want the changes that you did to the branch
on the trunk, too. The old state is therefore the branching point, the
new state the final version of the branch, and the application state the
current state of the trunk. Therefore:
1) Check out trunk, or update it to latest state.
2) svn merge .../branches/my-development-branch_at_branching-point
.../branches/my-development-branch_at_HEAD .
3) Resolve conflicts, test, and check in trunk.

Scenario 2: When you've made a release, you might want to port patches
on the trunk to the release branch and create a point release. So you
need to take changes on the trunk and apply them to the branch. The old
state is the trunk before the checkins you want to catch, the new state
is it afterwards, the application state is the branch.
1) Check out branch, or updated it to latest state.
2) svn merge .../trunk_at_rev-before-checkin .../trunk_at_rev-after-checkin .
3) Resolve conflicts, test, and check in branch. Be sure to mention the
revisions you merged in the commit message, as SVN doesn't track such
things in any way. E.g. "svn commit -m 'Merged r241 to r244 (bug
#350935). This will become release 2.14.5'".

One thing that is important to distinguish is release branches (the
state of a major release, for bugfixing and point releases) and
development branches (sandboxes for developing stuff). You can merge
trunk changes over to release branches (and vice versa, if a bug is
fixed on the release branch first), but you must never merge trunk
changes to development branches! The changes from these merges would be
picked up by the diffing of the branch's initial and final states. This
means that the merging would try to apply changes to the trunk that were
already made, hopelessly confusing the merger and making the merging
very, very difficult. So don't do it.
If you've spent so much time on a development that your patch is
hopelessly out of date, you do this: create another branch based on the
most recent trunk state, merge the changes of your original branch to
this new one as you would merge them to the trunk, then fix everything
that doesn't work. Then, merge the changes done on this new branch to
the trunk.

Maybe someone will find this little tutorial useful.

Sebastian Redl