Branching
Developers are encouraged to work in branches, and merge their changes after running the full test suite against their branch. Generally developers will create their own branches with names of their choosing, hopefully a descriptive one. Release and patch release branches will be numbered, while feature or experimental branches should have readable names. You can see a list of active branches here.
Developers are responsible for keeping their branch fully up to date with the latest changes from trunk, before merging their changes back to trunk. This should keep conflicts and other problems to a minimum.
Please see below for the policy and tools for branching and merging.
Merging
There are myriad ways to solve problems, and branching in Subversion is no exception. There are two fundamental types of branches, private/feature branches and (patch) release candidate branches. Their merge styles are different, each is described below.
Feature and private branches
The "official" way to branch in the Terracotta tree for feature and private branches is to use the svnmerge.py
script, which is in the contrib part of the Subversion distribution, and for convenience in the source repository as /dev-tools/trunk/subversion/svnmerge.py.
Although it is certainly possible to use a different merging strategy than with svnmerge.py (using merge points/tags, etc.), developers are strongly encouraged to follow the standard method detailed below for private branches. It is required for feature branches, as there will likely be more than one developer working on it at a time and a standard is necessary.
Scripts to automate some or all of the steps below are in the works; when they are created they will most likely be located in /dev-tools/trunk/subversion.
How to do it
Here we'll go through all of the required steps to make a branch, keep your branch in sync, and merge your finished changes back to the trunk. For this example, we will assume that developer pat is going to create a private branch called jdk16-support in which to work.
This example looks really long, but that's mostly because of the wiki spacing and isn't actually too many steps. Once you do it once or twice it should be pretty easy, don't let the length of its description here scare you.
- Check out the dev-tools project
- Create a branch from trunk
- Check out the branch
- Initialize merge support in the branch working copy
- cd jdk16-support
- <path to dev-tools>/subversion/svnmerge.py init
- svn commit -F svnmerge-commit-message.txt
- rm svnmerge-commit-message.txt
- Do some some work in the branch and check in the changes...
- Merge latest changes from the trunk into your branch
- cd some-directory/jdk16-support
- <path to dev-tools>/subversion/svnmerge.py merge
 | Whenever you run the svnmerge.py merge command, pay close attention to the output and look for conflicts or anything else that might be problematic |
- ...resolve any conflicts...
- svn commit -F svnmerge-commit-message.txt
- rm svnmerge-commit-message.txt
- Repeat the previous two steps until you are ready to merge your branch back into the trunk
- Merge your changes to the trunk
-
-
- ...resolve any conflicts...
-
- Commit the merge, but discard the changes made to the svnmerge-integrated/svnmerge-blocked property on /trunk
- svn propdel svnmerge-integrated .
- svn propdel svnmerge-blocked .
- svn commit -m 'Your descriptive commit message'
- Remove your branch
- Done
Important notes about the example
- The 'dso' project is used in this example, but it extends to other projects as well (such as 'dev-tools')
Release candidate and patch release branches
(Patch) release candidate branches have a fundamentally different life cycle that feature branches. Feature branches need to stay up to date with trunk their entire life, and then all of their changes are merged back to trunk at the end of the life cycle. (Patch) release candidate branches, however, never take changes from trunk, live only for the duration of the QA period before a release and should only contain bug fixes. With patch release branches it is also likely that a change made there should not be merged to trunk as it may be a) out of date, b) already fixed or c) undesirable for some other reason. As such, there should be (hopefully) very few, isolated changes in these branches.
To start with, each developer will be responsible for merging their bug fixes in a release candidate branch to trunk, and should be done on an individual basis (just like the bug fix you are making, right?). If this becomes unreasonable we can always change it, but this has a few advantages:
- trunk does not get cluttered up with multiple values in the svnmerge-integrated property when using svnmerge.py: that makes merging the more common feature branches much easier
- bug fixes are merged by the developer doing them while the code is in mind, possibly against newer code in trunk which might require a decision as to whether the change should even be merged to trunk at all
- it doesn't take very long
How to do it
For these types of branches, the release team will be responsible for creating the branch and will send a link to their location so creation here is not necessary.
- Check out the candidate branch
- Fix your bug in the candidate branch and check in the changes, assume for this example it is revision 12345
- Decide if you should merge this fix to trunk, if not (for whatever reason) you are done; if so go to the next step
- Merge your individual change to the trunk (note the -r argument and trailing '.' argument, more detail below)
- cd trunk-working-copy
- svn merge -r12344:12345 https://svn.terracotta.org/repo/tc/dso/branches/2.2.0 .
- ...resolve any conflicts...
- ...verify your change...
- ...commit your change, making sure to indicate what branch and revision you merged in addition to a brief summary and bug number...
- Done
Important notes about the example
- In the svn merge command the -r option has two revision arguments; if the revision you are trying to merge is N, then your arguments should look like -rN-1:N.
 | Subversion 1.4 only
You can use the new -cN argument instead, which is shorthand for -rN-1:N |
External svnmerge.py links
- The svnmerge.py wiki page; this contains other links/resources and is the canonical place to go
