SVN Branching and Merging

For basic subversion usage and information about our repository, see this page.

In the below documentation, $SVN represents the svn root - currently that is at file:///p/vdt/workspace/svn/vdt.

Branching

Branches are stored in $SVN/vdt/branches.
For VDT version branches, names should be of the form vdt-X.Y or vdt-X.Y.Z, e.g. vdt-1.8 or vdt-1.8.1
When creating a branch to do some test development work, the name should include both the branch it came from, as well as an indicator of what work is done in the branch. For example, if a branch is made from the vdt-1.8.1 branch to do some stunnel work, the name should be vdt-1.8.1-stunnel.

To create a branch:

svn cp source dest

# For example, to branch 1.8.2 from the 1.8 branch
svn cp $SVN/vdt/branches/vdt-1.8 $SVN/vdt/branches/vdt-1.8.2

Tagging

Tags should include the branch name, followed by an identifier.

For VDT version tags, the tag should be of the form <branch-name><release letter>. For example, vdt-1.8.1, vdt-1.8.1a, vdt-1.8.1b, etc.
Tags created on special (unreleased) development branches should include the branch name, followed by an identifier to make it clear where the last merge point was. For example, vdt-1.8.1-stunnel-merge1, vdt-1.8.1-stunnel-merge2, etc.

Merging

Most of our lettered release merges apply smoothly. However, files/directories are renamed, there are additional steps needed. Here is an example of a complicated merge involving renamed files/dirs and some extra instructions. It is not important to read now, it is included here as a reference for those situations.

The following examples assume that the shell variable SVN is set to file:///p/vdt/workspace/svn. In csh-like shells:

setenv SVN file:///p/vdt/workspace/svn

In sh-like shells:

SVN=file:///p/vdt/workspace/svn

If you are about to perform a merge, create a tag. If you just created a tag for a release, use that tag. If you did not do a release, and have not yet created a tag, do so now (look at the section above on tagging for help naming the tag). This helps keep track of where the last merge point was on a given branch. The tag will likely look something like:
```
svn copy $SVN/vdt/branches/vdt-1.8.1-dcache $SVN/vdt/tags/vdt-1.8.1-dcache-merge1
```
Get a checkout of the branch that you are going to merge into.
```
svn co $SVN/vdt/trunk
```
or
```
svn co $SVN/vdt/branches/BRANCH
```
Determine what tags/branches you are merging between.
- For lettered releases, this is usually the tag that was just created, and the previous release tag. For example, (vdt-1.8.0e and vdt-1.8.0f) or (vdt-1.8.1 and vdt-1.8.1a).
- For merging changes on a branch back to the trunk, .... (fill this in)

Run a dry run merge. From the checkout that you just made (of the branch you want to merge into):

cd fresh-checkout-directory

# Run the dry-run merge.  Note the . at the end of the command line.  This is where you are merging into.
svn merge --dry-run $SVN/vdt/(branches|tags)/OLD $SVN/vdt/(branches|tags)/NEW .
# e.g. svn merge --dry-run $SVN/vdt/tags/vdt-1.8.1 $SVN/vdt/tags/vdt-1.8.1a .

Examine the changes that would be applied if this were actually doing the merge. Does everything look good? If not, you can do an 'svn diff' to see what changed.

svn diff $SVN/vdt/(branches|tags)/OLD $SVN/vdt/(branches|tags)/NEW

# Questions about a specific package that changed?
svn diff $SVN/vdt/(branches|tags)/OLD/Package $SVN/vdt/(branches|tags)/NEW/Package

All the changes look good? Now run the real merge. Same as above, without the --dry-run flag.
```
svn merge $SVN/vdt/(branches|tags)/OLD $SVN/vdt/(branches|tags)/NEW .
```
Watch for "Skipped missing target" messages. This means that the checkout you are in does not have the right directory/file to apply changes to. Handle appropriately. Here is an example involving directories changing names.
Examine the changes, using 'svn diff' as necessary. Resolve any conflicts, then run 'svn resolved' on those files.
Check everything in, and include the merge command used in the checkin comment so that it can easily be determined later where a change came from (there may be a more subversion-y way of finding out this info, but this makes life easy).