Vendor Branches: The Problem

anne's picture

Managing your own customisations to a project such as OfBiz, while still being able to update when desired from the trunk version, is not simple. We tried many approaches over the years, and have finally found one we are happy with. It takes a little getting used to, but we’ve found it to be reliable and far less painful than any of the other methods we’ve tried.

We tried several systems involving CVS or Subversion, but they all seemed to cause more problems than they solved. Our successful system consists of a combination of careful code design, the Mercurial source control management tool, the Mercurial Queues Extension, and unit tests.

Before I describe the system we now successfully use, let me describe the problem.

The Problem

Our starting point is source code that does a lot of what we need, maintained by others. We need to change this source code so it does everything we need, rather than just most of what we need.

If you have the relevant skills, it is trivial to take the source code and change it to suit your requirements. But if the maintainers of that code subsequently make changes, perhaps to add new features or fix bugs, it is likely to be a lot of work to update your customised version with those changes. If the original code is small, or if your changes are few, then a source control system such as Subversion or CVS can automate a lot of the effort, and the task becomes possible. The web has quite a few sites with details of this process. For example Vendor Branches, Subversion Vendor Branches Howto, Subversion Vendor Branches, and there are plenty of others.

Using vendor branches sounds easy. However for a large original code base (such as OfBiz), with wide-ranging customisations, we found that updating could involve several days in front of a merge tool. It was way too easy to make an error, and either introduce bugs or delete a customisation. We also had problems when files or directories were removed, and when we copied an original file into a directory we had created. In short, managing a vendor branch was taking way too much of our time, causing bugs, leaving cruft, and not helping us manage all types of customisations.

We also discovered a type of customisation that was important to us, but was very difficult to manage with other systems we attempted to use. Sometimes the best way to customise an aspect of the OfBiz user interface was to copy an existing user interface definition (for example, a freemarker file) from the vendor code to a location under hot-deploy, alter it as necessary, and point the relevant code to use it instead of the original.

This worked well, until the vendor updated the original. That update was not applied to our copy, and so we missed out on bug fixes and feature additions. Even worse, updates to the environment could break our copy. For example, should the vendor code switch to using jQuery from an older technology, our altered screen would no longer work.

In my next article, I will describe the solution we now use.

Next: Vendor Branches: The Solution