Managing Your Source Differences

Managing Your Source Differences

When customizing OFBiz components for your specific business requirements you will most likely come across situations where small changes to files are needed and it doesn't make sense to replace a component completely or attach logic to it through Service ECA rules or other means. So, how should you manage the differences between your code and the OFBiz baseline code so that updating from the OFBiz baseline will be as painless as possible?

The first thing you should always do is isolate your chagnes and comment them so that it is easy to distringuish what you changed from the OFBiz baseline code. The final goal is to make it easy to merge your changes with future changes in the OFBiz baseline.

There are various ways to structure your internal CVS or other code repository. One very flexible, but laborious, way is to create a complete copy of the OFBiz CVS tree in a module in your own CVS repository. This could perhaps be called "ofbizbase". This should contain the revisions of the code that you are currently working with and allows you to selectively incorporate specific changes from the OFBiz baseline. These files should be direct copies from a revision in the OFBiz CVS repository. If you make changes in this module that are not part from the OFBiz baseline they should be temporary changes that are meant to be overwritten and replaced with future versions from the OFBiz baseline.

Once your ofbizbase snapshot module as described above is in place you should create another module, maybe called "ofbizdiff". This will contain ONLY the files that you have changed relative to your ofbizbase module. When updating the version of a file in your ofbizbase repository from the OFBiz baseline you should do a three way diff/merge to make sure the changes in the OFBiz baseline make it into the version of the file in your ofbizdiff module as well as the file in your ofbizbase module.

The three way diff/merge will be done with the following three files: the old file from your ofbizbase module as the base, your changed file in your ofbizdiff module as the merge target, and the new file from the OFBiz baseline as the merge source.

The build process for this sort of a structure is very simple. Create a temporary build directory. Copy the entire ofbizbase tree into the directory. Copy the entire ofbizdiff tree into that directory, replacing files as needed. In the root of the temporary build directory run the Ant build file. What could be more simple?

When editing files in your ofbizdiff module you should ALWAYS edit them in place in the ofbizdiff directory tree and copy them to the temporary build directory for testing. Doing this you will always be able to do a CVS update to see which files you have modified as you are working.

Many variations on this technique can be effectively used. If you don't plan to make temporary changes to ofbizbase files or update individual ofbizbase files selectively, you may do just fine with an archive (like a zip or tar.gz file) instead of a CVS module for your ofbizbase tree. You could keep the current version of this archive in your ofbizdiff CVS module.

We have heard a lot of questions about using simple merge scripts to apply differences to source in the ofbizdiff tree so that full files do not have to be stored ant maintained there. This is fine, but it is a LOT harder to perform the diff/merge or other code synchronization when you don't have the complete files to do a three way diff/merge. So, we don't recommend using minimal diff files that can be applied as part of preparation for the build process. Just copy the file from ofbizbase to ofbizdiff and make the changes you need as recommended above.

For Those Comfortable With CVS Branching/Merging

If you are comfortable with the branching and merging features in CVS you can use those very effectively to easily maintain you differences from the OFBiz base source tree, and still keep up-to-date with the latest from OFBiz without too much trouble. CVS does three-way diff/merge operations all the time when doing updates, and this same feature can be used to do the three-way diff/merge described above, but in an automatic way that only requires your involvement for merge collisions.
To get started do a fresh checkout from the OFBiz CVS repository, then remove all CVS directories and import the tree into a new module in your local CVS repository. Tag this set of files with a name like OFBIZ_20030612 (adjust for the current date) using a command like "cvs tag -b OFBIZ_20030612". Now just change/add things as you please. Note that you are not working on that branch, you are working on the HEAD branch unless you do something like "cvs update -rOFBIZ_20030612".

So, now you have a bona-fide branch of OFBiz with your own code mixed in, but there are a ton of cool new things in the latest OFBiz base code that you would LOVE to have. What do you do? The easiest way to do this is to use the "cvs import" command, and you can do this multiple times to get a new vendor branch for the latest OFBiz code. For example, checkout the latest OFBiz code (with an export or a checkout) and from the root directory of that import run something like 'cvs import myofbiz OFBIZ_BASE REL_3_0_0 -m "More cool stuff from OFBiz"', where myofbiz is the name of your local CVS repository module, and OFBIZ_BASE string you use to identify this vendor branch, and REL_3_0_0 is a string you use to identify the current set of code from OFBiz. This could also be date based if it isn't from an official OFBiz release or tag.

Go back to the place on your machine where you have HEAD checked out and merge the branch you just created with the HEAD, or the current set of files you have checked out. To do this run something like "cvs update -dP -j[the-ofbiz-tag]".

At any time to get a list of all files changed from the base, get a list of all tags on the module and compare the HEAD revisions with the revisions tagged using the most recent OFBiz tag.