March 29, 2011

DocBook with Maven Issue

We are using DocBook for writing technical documentation for all our projects and in-house frameworks. We are actually quite happy with this approach, especially because we are able to automatically publish the docs in a number of formats, including HTML and PDF. To do so, we use the docbkx-maven-plugin in the project's nightly build.

So, all has been in best order... until I decided to upgrade this docbkx-maven-plugin from version 2.0.8 to current version 2.0.11 (due to some issues we had). After doing so, the document conversion issues an error which breaks the build:

[ERROR] Failed to execute goal com.agilejava.docbkx:docbkx-maven-plugin:2.0.11:generate-pdf (pdf) on project builddoc-ma
ven-plugin: Failed to transform to PDF: org.apache.fop.fo.ValidationException: null:30:723: Error(30/723): fo:table-body
is missing child elements.
[ERROR] Required Content Model: marker* (table-row+|table-cell+)

Well, this is somewhat unexpected because I didn't change anything but the plugin version, and I don't see any reason it could not work as before. In particular, we are still using the same docbook version in our POM. Here is the relevant snippet:

<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>2.0.11</version>
<dependencies>
<!-- the DocBook XML DTD and catalog files (see http://www.oasis-open.org/docbook) -->
<dependency>
<groupId>org.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>4.4</version>
<scope>runtime</scope>
</dependency>
</dependencies>

<executions>
<execution>
<id>pdf</id>
<goals>
<goal>generate-pdf</goal>
</goals>
<phase>post-site</phase>
<configuration>
...
</configuration>
</execution>
...
</executions>

<configuration>
<htmlStylesheet>css/html.css</htmlStylesheet>
<htmlCustomization>${basedir}/src/doc/xsl/html_chunk_customization.xsl</htmlCustomization>
<foCustomization>${basedir}/src/doc/xsl/fopdf_customization.xsl</foCustomization>
...
</configuration>
</plugin>

It's important to understand that we are using the advanced customizing capabilities of DocBook, i.e. we customized the stylesheets used for rendering HTML and PDF. The created custom stylesheets contain an import to urn:docbkx:stylesheet, and in the Maven POM the htmlCustomization and foCustomization properties point to those custom stylesheets. This is how it's supposed to be, and this is how it worked all along.

I found out that the error message is correct when building with plugin version greater than 2.0.8, since the for-each element indeed does not return any element which results in an empty fo:table-body. In fact, none of the xsl:value-of in our customized stylesheet returned any value any more....

So here is why: since docbkx-maven-plugin version 2.0.9, the plugin is using namespaced stylesheets. That is, we must use a namespace in our custom stylesheet to be able to select any docbook element! See this or this post for related comments.

Thus, all I have to do is to add the docbook namespace declaration at the top and add the docbook namespace prefix to all references to element names in my customization layer. See highlighted lines in this XSL snippet:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:db="http://docbook.org/ns/docbook"
exclude-result-prefixes="date"
version="1.0">

<xsl:template name="book.titlepage.separator">
<fo:block>
<fo:table table-layout="fixed" width="163mm">
...
<fo:table-body text-align="left">
<xsl:for-each select="/db:book/db:bookinfo/db:revhistory/db:revision">
...
</xsl:for-each>
</fo:table-body>
</fo:table>
</fo:block>
</xsl:template>
...
</xsl:stylesheet>

Well, that did the trick – after spending a couple of hours of investigation... I think that issue should be clearly noted with the docbkx-maven-plugin Maven plugin, because in the end it is an incompatability between versions 2.0.8 and 2.0.9. Alas, I did not find this information on the plugin's Changes Report page. At least, nothing that pointed me (not being a DocBook expert) into this direction... :-(

March 21, 2011

The Way From Hudson To Jenkins

Some time has gone by since the Hudson/Jenkins fork... and there has been even more talk in the community. However, slowly the dust settles, everybody is getting back to business. And finally, we decided to switch from Hudson to Jenkins! This is about why and how.

Why move to Jenkins?

But wait: who has forked, anyways? Is it Jenkins that forked Hudson, or is it Hudson that did the fork of Jenkins? There is some evidence that the community just did a rename of the project (due to trademark conflicts), and after that Oracle forked Jenkins, using the Hudson name they claim holding the trademark on.

You may think this question is a purely theoretical one, but actually it's not. I'll have to legitimate the decision to move to Jenkins to my stakeholders, and using a fork would be a "smell". Project forks are usually not as good as the "original", are possibly done out of selfish reasons, are considered to harm the community etc. Hence, not moving to a fork but instead following the "real" project is a good reason for the move to Jenkins.

An even better one is "project vibrancy", that is the pace of development and level of support provided by the community. This is usually measured by indicators such as the number of commits, the mailing list traffic, the quantity, quality and regularity of releases etc. See this post for such an analysis on commit counts and mailing lists post counts. This is more than four weeks old now and covers not more than two weeks, but nevertheless the result is obvious: Jenkins moves much faster than Hudson does, and community is much more agile. This is confirmed by following the dev mailing lists of both: for Hudson, most of the relevant posts are by either Oracle or Sonatype engineers – seems the Hudson community has become pretty small... Moreover, as this post shows, most of the top plugins will continue primary development under Jenkins.

Last not least, I really respect Kohsuke Kawaguchi (the original creator of Hudson) and what he has done for us. I feel ashamed by how Oracle is dealing with him and the rest of the core team, that's why I have a strong tendency to follow the "good guys" with Jenkins.

As I blogged before, Maven integration is probably one of the most important features of any CI server (at least for me). I guess Sonatype is doing better with Maven integration – it's "The Maven Company", right? – and they are working with Oracle on Hudson. At least, they are putting huge efforts into rock-solid integration. However, after having seen a Sonatype Webinar about their plans with Hudson, I'm not that convinced any more. Current features looked a bit awkward and also does the GWT based UI they are using. So, from my point of view, this point is not yet decided.

Counting it all together, there are some really good reasons to move from Hudson to Jenkins, so we did.

How to upgrade

Now... how do you actually migrate from Hudson to Jenkins? Well, it couldn't be easier. There is a Wiki page about Upgrading from Hudson to Jenkins. To make it short, the involved steps are:


  1. Backup your current installation – just for the good feeling.

  2. Change Update Site: In your Hudson, go to Manage Hudson > Plugin Management > Advanced > Update Site and enter "http://updates.jenkins-ci.org/update-center.json" as URL for Jenkins update site.

  3. Choose to upgrade automatically on Manage Hudson page, just as you did so many times to update Hudson. This will download the new JAR.

  4. Restart Hudson, eh, Jenkins.... and there it is!

That's it. Took less than 5 min! Hudson indeed is a drop-in replacement, so you usually do not have to change anything (environment variables, system properties, start scripts, job configuration etc).

Well, there is only one thing: the name of the WAR file is still hudson.war! Is Oracle aware of this? ;-)