SvnBranchThenMerge

== Branching ==

A common approach towards developing experimental features is to make a local copy of the source code, hack on it until the desired feature works, then commit the results into the repository.

Subversion is designed so that it is cheap (w.r.t. time and space) to make copies of files in the repsitory. Therefore, a useful pattern is follow the above approach, except that you also keep the "copy" in the repository. This is known as a "branch."

The benefits of using a branch within subversion (rather than a private copy on the hard drive) are:

• Development history of the branch is recorded
• Easy deployment onto different systems for testing (just check out a copy of the branch from the repository)
• Integration into Subversion and Trac

The main costs are that you need to understand how to use the appropriate subversion commands, and that your changes are no longer privately held. But we're not embarressed about the code we write around here, right? :)

The commands for creating a branch of larceny_src:

1. Create a directory in the repository to hold the branch, with svn mkdir
2. Copy the source tree from the trunk of the repository into the branch, with svn cp
3. Checkout the branch version onto your machine, with svn checkout

e.g.

% svn mkdir file:///proj/will/pnkfelix/svn-archives/branches/will/mybranch
% svn cp file:///proj/will/pnkfelix/svn-archives/trunk/larceny_src              \
         file:///proj/will/pnkfelix/svn-archives/branches/will/mybranch
% cd ../../the-directory-for-my-branches-whereever-they-might-be/
% svn checkout file:///proj/will/pnkfelix/svn-archives/branches/will/mybranch

Now your branch directory holds a new copy of the source tree, and you are free to hack on code and commit your changes, without worrying about corrupting the trunk.

Merging

After you are done with development and have a feature that is ready to be committed to the trunk, you do a merge.

The steps in doing a merge are:

1. Determine what changes were made in the branch

• Determine where on the trunk the branch was copied from; take note of that version number.
  • PnkFelix finds the Trac source browser useful for this step, but svn log could also be used for the same purpose.
• Consider using svn diff to review the changes as a sanity check
  • The syntax for the diff and merge commands deliberately overlap, so that one can easily review the expected changes with one command and then easily switch to doing a merge

1. Checkout a clean copy of the trunk (if you don't already have one), with svn checkout
2. Incorporate those changes into a working checkout of the trunk, with svn merge
3. Resolve conflicts (sorry, svn can't help you here).

• Conflicts should be marked in the output from the merge command with a C on the front of the line.
• Conflicts are marked in the meta-data that subversion maintains, so you can find out what conflicts currently exist with the svn status command
• Since conflicts are stored in the subversion meta-data, you need to explicitly resolve them with the svn resolved command.

1. Commit the codebase with the changes from the branch, with svn commit

• important: in the change log for the commit, include a reference to the branch, including its version number at the point of the merge.
• This step is important for people using the Trac source browser to understand the code's history.
• We want to give them an easy link to the history. You should use the Trac notation to refer to the branch, with its source:path@version WikiFormatting syntax.
• PnkFelix thinks its important to include the version number, so that further development can proceed on the branch without the history being confused on the changelog. (The main problem we're trying to compensate for here is that Subversion does not record the sources of merges in the meta-information after you perform an svn merge, so we need to explicitly add such history if we want the users to be able to see where things came from.)
• (Doing further development on an existing branch is a bit of an advanced topic, since it requires a bit more thought about the arguments to the merge command when you want to merge your changes back into the trunk.)

e.g.

% svn checkout file:///proj/will/pnkfelix/svn-archives/trunk/larceny_src
% svn diff  file:///proj/will/pnkfelix/svn-archives/trunk/larceny_src@1600   \
            file:///proj/will/pnkfelix/svn-archives/branches/will/mybranch/larceny_src@1800
### Eyeball the diff to make sure its what you want
% svn merge file:///proj/will/pnkfelix/svn-archives/trunk/larceny_src@1600   \ 
            file:///proj/will/pnkfelix/svn-archives/branches/will/mybranch/larceny_src@1800
### Resolve conflicts in your source base, if necessary (use 'svn resolved' to mark them as resolved)
% svn commit -m \
  "Added feature X; its great.  Merged from source:/branches/will/mybranch/larceny_src@1800"