Skip to main content

The 'Continuous Integration with Hudson' book build process

Posted by johnsmart on April 5, 2010 at 12:13 PM PDT

Continuous Integration with Hudson is a new open source book project in the works. In the spirit of 'eating our own dogfood', this book is produced using Hudson. In this article, I discuss the build framework used for the 'Continuous Integration with Hudson' book.

The 'Continuous Integration with Hudson' book is written in docbook, and is therefore XML source code which builds to PDF and HTML versions of the book. The source code is stored using git (in a github repository which will be eventually made public). The main branches are the following:

  • master - the main development/integration branch
  • review - review candidate versions go here
  • release - the current latest release version

 

There is also a branch for each chapter, which gets merged into the master branch when it is ready to be integrated into the whole book. When they are ready for review, chapters are merged into the review branch. A team of volunteer technical reviews the review candidate, and fixes are integrated into the review branch, and then ported back into the master branch. When the review branch is ready, the new chapter is merged into the release branch.

Needless to say, git merging and branching makes it much easier to update additions and corrections across branches - it is trivially easy to update the review candidate branch with the latest chapter, and to move corrections made during the review process from the review branch back to the master branch, for example.

The docbook XML source code is built into PDF and HTML form using Maven. This process is based on the one developed by Tim O'Brian for the excellent Maven and Nexus books, and it works well.

The build process is automated using Hudson. There is a build job on each of the main branches (master, review and release, and the more long-lived chapter branches). The Hudson build job builds PDF and HTML versions of the source code. It also checks for docbook errors and warning such as missing figures or cross-references, and keeps track of TODO tags (using the 'Open Tasks' plugin).

The 'release' build job automatically deploys the latest version of the book to the 'Continuous Integration with Hudson' web page (using the SCP plugin), so the version found here is always guaranteed to be the latest and greatest.

You can see a high-level overview of this architecture here:

This process is still evolving. Things coming up soon on the roadmap include archiving and deploying the HTML version of the book as well as the PDF, and integrating an automatic spell checker in the Hudson build process.

Related Topics >>

Comments

This is very appreciated,

This is very appreciated, John - as usual, but today a bit more than usual. I'd like to start writing a book too, about my experience with the NetBeans Platform, and the idea is to collect, reorganize and update my various blog posts of the past years. I've already gotten the suggestion of using docbook, but I was still missing a piece about how to set up a workflow. Call me maximalist (*), but often if I don't have a good idea about a workflow, I'm unable to start a thing.

 

(*) I'm unsure about the translation of this term. In Italian, the original term is used e.g. to describe people that always think of a plan to do things where everything is equally important - in this context, I'd say it's the opposite of "incremental" (hence, it's a defect of mine, even though it only applies at the inception of a thing and not during the evolution).

Book/Article about book writing process

Hi John, It would be a great idea to share with the open source community how you build this book. Links to(or) tutorials on docbook editing and how to setup the whole infrastructure would help other developers write books. Currently, among the big tech publishing houses, pragmatic programmers and O'Reilly have this kind of infrastructure where developers get their subversion repository and automatic book building process. More developers will think about publishing once the process for doing a book is made easier. I know that there is a lot more to publishing a successful book than the "building" infrastructure but if we can remove more hurdles, then all the better. Thank you, BR, ~A