Branching

Student projects, or other projects independent from the main development, are better performed on a branch instead of the trunk. Students can then make changes, work together in relative isolation, and supervisors can inspect intermediate results and monitor progress by reading commit messages. Finally, since these projects are experimental in nature, a decision can be made to incorporate the changes in the trunk.

This page describes how to deal with branching using Subversion:

Create a branch

• Checkout the trunk first and make sure that your environment is properly setup to build shuffle, ruler, the ehc compilers, and the phd thesis pdf file. If not, check older versions of the trunk or contact the repository owner:

  %svn checkout https://subversion.cs.uu.nl/repos/project.UHC.pub/trunk/EHC
         

• Use:

  % svn info
         

  to obtain the current version of the trunk; say R.
• Create a branch using:

  % svn copy --revision R https://subversion.cs.uu.nl/repos/project.UHC.pub/trunk
                          https://subversion.cs.uu.nl/repos/project.UHC.pub/branches/your_branch_name
         

• Mention in the commit message that you copied revision R of the trunk to the branch and write in a few words where you are going to use the branch for.
• Switch your working copy to the branch you just created:

  % svn switch https://subversion.cs.uu.nl/repos/project.UHC.pub/branches/your_branch_name/EHC
         

Regression tests

The EHC project contains a facility for regression tests. Use a revision of the EH project from before you made your own changes!

For example:

• Make sure all changes in your branch are committed (say revision Z).
• Checkout a clean copy of the trunk:

  % svn checkout --revision R https://subversion.cs.uu.nl/repos/project.UHC.pub/trunk/EHC EHC-trunk
  % cd EHC-trunk
         

  (omit the revision flag for the HEAD revision of the trunk).
• Build the compilers and run:

  % make test-expect
         

  As a result a series of files containing expected output are produced in the test folder.
• Remove the fresh checkout of the trunk
• Build the compilers in your own working copy and run:

  % make test-regress
         

• Inspect possible differences between the given output and the expected output.

Merge back to the trunk

• Verify that the diversity of tools within the EHC project still build
• Use the regression tests to verify that the compilers still work as expected
• Make sure that all changes in your branch are committed.
• Lookup the revision number of the creation of the branch K (typically *R*+1)
• Checkout a clean copy of the trunk:

  % svn checkout https://subversion.cs.uu.nl/repos/project.UHC.pub/trunk/EHC EHC-trunk
  % cd EHC-trunk
         

• Build the compilers
• Create expected output:

  % make test-expect
         

• Merge the changes you did in the branch to the working copy:

  % svn merge --revision K:HEAD https://subversion.cs.uu.nl/repos/project.UHC.pub/branches/your_branch_name/EHC .
         

• Resolve conflicts (typically imports/exports and relocations of code)
• Build the compilers, tools, etc and run:

  % make test-regress
         

• Take possible differences into consideration (possibly you changes some of the tests, then differences are to be expected).
• Run:

  % svn update
         

  To verify if somebody made a change to the trunk in the meantime. If so, repeat the steps from resolving the conflicts, building the compilers and testing the results again.
• If everything is OK: commit (call the new revision Q) and write in the commit message that you merged revision Z of the branch to the trunk.
• Run svn update again to see if there are any changes in the meantime and check that everything is still OK.
• Remove your branch:

  % svn delete https://subversion.cs.uu.nl/repos/project.UHC.pub/branches/your_branch_name
         

  and specify in the commit message that you removed the branch because you merged it to trunk revision Q.
• Remove the fresh working copy.
• Remove the working copy of the branch, or switch it to the trunk.

Branches with a long lifetime

If your branch has a long lifetime (i.e. a Msc project that spans half a year before changes are incorporated in the trunk), you may want to periodically incorporate changes of the trunk to your branch (to stay up-to-date):

• Make sure your changes are committed.
• Lookup the last revision K on which you merged from the trunk to the branch.
• Apply changes from K to the HEAD to your working copy:

  % svn merge --revision K:HEAD https://subversion.cs.uu.nl/repos/project.UHC.pub/trunk/EHC .
        

• Resolve conflicts.
• Commit and write in the commit message that you merged K:HEAD to the trunk.

Merging back to the trunk is somewhat problematic. The differences between the beginning of the branch and the head revision of the branch already contain some of the differences between K and the HEAD of the trunk. Applying the steps of the previous section can result in duplicate changes.

A somewhat pragmatic way of dealing with this issue is:

• Get your branch in sync with the trunk (i.e. merge the trunk to the branch).
• Merge the entire branch as usual to the trunk.

This will give some problems due to repeated changes, but subversion will discover most of them by itself and result in only a handful of conflicts. Resolve these by preferring the version of the branch.

• If building the tools, or regression tests, give problems, make sure that you check the files in question for merge problems.

Alternatively, you can do it the hard way:

• Write down each interval on the branch between merges from trunk to branch and record the version of the trunk that corresponded with the beginning of each interval.
• Start with a fresh checkout of the trunk using the trunk-revision corresponding to the first interval.
• Apply each interval to your working copy:
  • svn update the working copy to the trunk-revision that corresponds to the beginning of the interval.
  • merge the changes of the interval on the branch to your working copy
  • resolve conflicts (you typically have to repeat the steps that you already took to merge the trunk to the branch)

-- ArieMiddelkoop - 14 Nov 2006