CouchDocs

Feature Branches

The CouchDB project uses feature branches to develop experimental features or refactorings without disrupting stability of the main trunk code.

All branches are kept directly under the incubator/couchdb/branches/ directory in the repository.

Creating a Branch

Feature branches are usually based on trunk. To create a branch, something like the following svn incantation should be used:

  svn cp <a href="https://svn.apache.org/repos/asf/incubator/couchdb/trunk">https://svn.apache.org/repos/asf/incubator/couchdb/trunk</a> \
    <a href="https://svn.apache.org/repos/asf/incubator/couchdb/branches/feature-name">https://svn.apache.org/repos/asf/incubator/couchdb/branches/feature-name</a>

Note that it's preferable to create the branch by specifying the full URLs to svn cp, as that won't let you end up with a branch based on different revisions of trunk, possibly because you forgot to svn up before creating the copy.

When that's done, checkout the new branch and initialize svnmerge, which we'll use to keep the branch in sync with trunk. For example:

  svn co <a href="https://svn.apache.org/repos/asf/incubator/couchdb/branches/feature-name">https://svn.apache.org/repos/asf/incubator/couchdb/branches/feature-name</a>       cd feature-name
  svnmerge init
  svn commit -m "Initialized svnmerge."

Keeping the Branch in Sync

Changes made in trunk need to be ported to the branch. This is done by utilizing svnmerge.

To see the changes available for being merged, use the svnmerge avail --log command.

To merge all the changes, use svnmerge merge. Or you can cherry-pick the changes to mark by specifying the revisions, for example svnmerge merge -r 123-125,188. If there's some change that you don't want to port (possibly because it no longer applies to the code on the branch), use svnmerge block -r 122.

As always with merging (and patching), be careful about properly resolving conflicts.

Merging the Branch Back into Trunk

When the branch has reached a certain level of stability, it should be merged back into trunk (assuming there's consensus that the branch is good and ready).

First, make sure that the feature branch is in sync with trunk, that is, merge any remaining changes on trunk to the branch as explained above.

Then, switch into the directory containing your working copy of trunk, use svn up to learn the latest revision (we'll pretend that's 12345), and issue an svn merge command like the following:

  cd trunk
  svn up
  svn merge https://svn.apache.org/repos/asf/incubator/couchdb/trunk@12345 \
    https://svn.apache.org/repos/asf/incubator/couchdb/branches/feature-name@12345

After the merge is done, please remember to clear the svnmerge-related properties from the trunk directory, to avoid problems with future branches:

  cd trunk
  svnmerge uninit

Feature Branches

Creating a Branch

Keeping the Branch in Sync

Merging the Branch Back into Trunk

Further Reading