Automated distribution creation

So we have this automated build with CruiseControl. It generates code, compiles, deploys, and tests. It’s saved my skin a gazillion times. It’s really great.

But it could be even better. It could also build a complete distribution, making the whole software release process a non-event. That’s one of my goals for the coming weeks. So stay tuned. 😉

Currently, the process to build a distribution of our product requires a couple of manual steps. One of these steps is to update the NEWS file, which describes the changes between releases. Of course, everything that changes between releases, is documented in the issue tracking system, in our case FogBugz. (FogBugz is OK to work with most of the time, although I think there are better alternatives, like Jira.)

FogBugz lets you add release notes to each issue (which it calls case), and it provides a standard report to show the release notes for all cases scheduled for a specific release. You can even download this report in XML.

The only problem is that this functionality doesn’t work most of the time. The only time when it is guaranteed to work, is when you try it on the server that hosts FogBugz. Since this machine is in the server room, this is inconvenient to say the least. But even if this functionality worked flawlessly every time, everywhere, it would still be a manual step to collect the XML file.

So I turned to HtmlUnit, a “browser for Java programs. It models HTML documents and provides an API that allows you to invoke pages, fill out forms, click links, etc… just like you do in your normal browser.” We use this great tool a lot to write our acceptance tests.

This time, I used HtmlUnit’s WebClient from within an Ant task to log in into FogBugz, generate the release notes report, extract cases with release notes (some cases have none, since they are too trivial to bother the end user with), and write them to an XML file. This allows me to transform the XML file to plain text using XSLT, giving a NEWS file section for the current release. The next step is to automagically add this to the existing NEWS file. This should be easy enough using Ant’s concat task. I will let you know how this works out.

The Power of Convention

I ran into some code the other day that wasn’t obvious to me right away. Why? Because it didn’t follow conventions. Let me explain.

In our system, we have what we call ‘binding objects’. These are objects that are persisted in our XML database and that we can use through Java interfaces. The code needed to access them is mostly boiler plate, so we generate it. Since the system was build on Java 1.4, we couldn’t use annotations for this. So, being an XML company, we naturally decided to describe the binding objects in XML and use XSLT to generate both the interface and the boiler plate implementation. We then add functionality by extending both of them.

Now, an often used convention in Java is to have the implementation for interface Xxx be named XxxImpl. We follow this convention often in our code, but for some reason did something else here. This cause me to look around wondering why I couldn’t find the implementation right away.

At this point, I’m sure someone will ask ‘So what?’. That’s always a good question 😉 For instance, in Eclipse, you would just select the interface and press either F4 to show the Type Hierarchy view, or Ctrl-T for a popup listing the same.

That’s true. But it requires a conscious action. Instead, if we had followed the convention, we would get this information for free. For instance, if both the interface and the implementation were in the same package, Eclipse’s Package Explorer would show them above each other. And even if they were in different packages, searching for the interface using Ctrl-Shift-T would also find the implementation. This free-riding is called a ‘widgetless feature‘. It is a Big Thing™ in user interface design.

Granted, it is a minor advantage. But this is just one example. Multiply by all the other places you can use conventions to reduce information overload, and you’ll find you’ll be more productive.

If you’re still not convinced, take advice from someone else. For instance, look at Maven: one of its central tenets is ‘convention over configuration‘.