KDiff3 Merge Tool for RTC

"3-way merges still remain one of the more taxing tasks of any software development team." (Wikipedia)

Rational Team Concert
For my current work I use Rational Team Concert, an Eclipse based IDE. RTC has a built-in compare tool that works well for comparing files or reviewing changes and furthermore Jazz Version Control offers various ways to resolve conflicts. But recently I had to merge a branch with more than a year worth of changes (more than 1000 commits) and the RTC merge tool showed certain deficiencies which had a negative impact on my productivity. So I looked for alternatives.

3-way Merge Tools
An ideal merge tool would be free and should support all platforms. Based on my experience and googling for 3-way merge, the following tools showed up in that particular order: KDiff3, P4Merge and DiffMerge.

KDiff3
KDiff3 is a free diff and merge program. It works on single files and whole directories. It runs on MS-Windows, Mac OSX and any Un*x that is supported by QT. It is GNU licensed which is ok for me but troubles our legal department ;-) Its installation is straight forward and it has direct Explorer integration on Windows systems. I have been using it to compare files for years. It is really cool, go check it out!

Integration with RTC
RTC allows a standalone merging tool to be used as a replacement of the internal one. To configure KDiff3 in RTC perform the following steps:

• Open the menu for Window -> Preferences.
• Select Team -> Jazz Source Control -> External Compare Tools.
• Choose <<custom>> in the drop down.
• Check off to use the external compare tool as the default open action.
• Browse to your KDiff3 install location for the executables.
• Use "${file1Path}" "${file2Path}" for the 2-Way Compare.
• Use "${ancestorFilePath}" "${file2Path}" "${file1Path}" -o "${mergeFilePath}" for the for the 3-Way Conflict Compare.

Usage
An external merge tool starts much slower than the integrated one. I do not recommend using it as the default open action. I use the internal one to see differences and only when I have to merge conflicts I choose Open in External Compare Tool from the context menu of the unresolved change:
Then KDiff3 starts and (hopefully) greets you with the message that all conflicts have been merged ;-) Often this is the case because the merge capabilities of KDiff3 are much stronger than of RTC, its Auto-Merge rarely works for me.
The user interface of KDiff3 is a bit crowded with windows. The top left diff-window (A) shows the base version, i.e. the common ancestor of both changed files. The middle window (B) shows the proposed changes and the right window (C) contains the current version of the file. The bottom panel is editable and allows you to solve conflicts, while showing the final output. KDiff3 immediately positions the cursor at the first unresolved conflict where you can use ctrl-1, 2 or 3 to do the merging. You can also use the ctrl-arrows to navigate the diffs.
Usually manual merging is a matter of a few key strokes. After saving and exiting KDiff3, RTC shows the changed file. Now select Resolve as Merged from the context menu of the unresolved change and the merge is finished.
If no changed file appears after saving the merge in KDiff3, that means that the merged version is the same as the current version. In this case select Resolve with Mine from the context menu of the unresolved change.

Other Tools
As mentioned in the beginning, there are two similar tools available: P4Merge and DiffMerge. P4Merge, the Perforce Visual Merge Tool, is part of the version control system Perforce. To only install P4Merge, deselect everything except Visual Merge Tool during install. P4Merge compares files, folders and images. It is much like KDiff3, shows three diff windows and the bottom pane is editable. DiffMerge is from SourceGear, another vendor of version control systems. It compares files and folders and has Windows Explorer menu integration like KDiff3. Both tools can be found in the drop-down list of supported RTC external compare tools and the arguments should not require any changes.

Waterfall and Requirements

We are doing Waterfall. "They" want it to be called Agile using Scrum, but it really is Waterfall. We have nine month release cycles including two months requirements gathering followed by four months development and three months of testing and defect fixing. Before we took over the project it had no process at all, so it is OK now, at least it follows some process. Waterfall is not that bad after all ;-) Currently we are at the end of the development phase and our last sprint will end next Thursday.

Some time ago, the customer suddenly found additional budget and decided to have another requirement implemented. (I have no idea how big organizations can suddenly find more budget, maybe under the mattress of the CEO?) We (the development team) were already booked up with requirements, so he brought in some special people from "Lab X". Lab X is located in off-shoring country Y, but that is not the point here, so let's just assume he found them under a stone. People from lab X had no opportunity to get to know our application, which is eally complex, a Big Ball of Mud with cryptic use cases. Finding your way around our one million lines code base usually takes more than six months for experienced developers.

I had heard about that additional requirement some time ago, but was busy and did not pay much attention. Recently things went bad. The senior developer from Lab X left the company or got rotated to another project, which had already happened before (in another release cycle - another story). I heard that it is common for developers to switch companies in country Y if they get a better offer from a competitor. One or two new junior developers were brought in to continue his work. From what I saw of their code, I do not think they deserve the word "junior" at all: someJavaString == "" is a clear sign that someone has no idea how Java works nor did he or she test the code. I do not blame them, it is not their fault. If you cannot find experienced developers, you have to hire new ones and train them, coach them and let them grow. Maybe they are experienced in another language, I do not know. I just know to expect these things from cheap labour service centres of country Y, where nothing is a problem and everything will be dealt with. "No problem Sir, it will be handled. Everything is OK now."

Right from the beginning two members of our team were asked to team up with the lab to help integrating their code into our product, which - of course - would not need much time. As far as I know they already worked five times as much on the integration as estimated and one went so far to implement parts of the solution on his own time and give it to the lab people to use it instead of their crap, which had not worked. I believe that he should not do that, but I respect my team member to have his reasons, so let him work double shifts if he feels like.

Early on the cycle, some executive or a project manager had signed a document to approve the inclusion of this new feature, so we have no option to escape this mess. I was told that the project manager keeps reminding the customer that his actions have been proven to be problematic but from what I know, the customer's representative is a true alpha-being and will not listen to anything he does not like. (I once had a phone call with a similar executive where I wanted to discuss a certain problem, but during the one hour call I was unable to say a single sentence, so obviously there was no problem and no actions were taken. I really need to improve my communication skills ;-)

So everybody works hard and the current release will be a success including the extra feature, the customer will be happy and nobody will learn anything. As soon as the new feature will be in production, the resources from lab X will vanish and we will be stuck in the quicksand a bit deeper. I hope that the world ends this Xmas as predicted by the Maya calendar and all this ends.

Eclipse Plugin Development

My friend Piotr asked me where to start with Eclipse/RCP development. I am not an expert on Eclipse but it is the main platform of my current employer, and I collected some information while digging deeper into the topic myself. Following an advice from Scott Hanselman I write this blog post instead of an email. This is my list for developers starting with Eclipse development.

• The first pages to read are the Eclipse Plugin and Eclipse RCP Tutorials by Lars Vogella. These are short tutorials with good content which are highly relevant. You might want to start here.
  
  
• Another source for tutorials is G. Prakash's Eclipse Tips, especially his top ten mistakes in Eclipse Plug-in development are highly recommended.
  
  
• More details can be found in the book about Eclipse, Eclipse Rich Client Platform by Jeff McAffer, Jean-Michel Lemieux and Chris Aniszczyk. Throughout the book the authors build an entire application, set up the automated build, create an update site and everything else. This is a comprehensive end to end description.
  
  
• The Eclipse website itself hosts a lot of specialized information. My favourite article is about how to use the JFace Tree Viewer. This does not only show how to use the Tree Viewer, it also explains how to "think in JFace" in general.
  
  
• Finally a lot of articles can be found on IBM developerWorks, just search for RCP. These articles are older, mainly from 2006 to 2008, but most things discussed there are still relevant.

That should be more than enough to get you started ;-)