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
% 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
- 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
The EHC project contains a facility for regression tests. Use a revision of the EH project
from before you made your own changes!
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).
% 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.
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):
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)
- 14 Nov 2006