Al Hoang

Hello (openwfe) World

John Mettraux who is the project lead for OpenWFE has given me commit rights to his Ruby port of
OpenWFE.

I have to say I’m flattered by the trust in receiving commit rights considering:

1. I have no experience with workflow systems
2. I’m not exactly a Ruby expert

First thing I did was check out the source and noticed that the rdoc for the source was reasonable but lacked examples for getting started. For a simpler library like Math this might be doable however a workflow engine has quite a few moving parts so it’s hard to know where to start.

I decided that my first task would be to add some examples to get someone else up to speed (such a myself) without having to crawl through the unit tests. However, after updating the README.txt I was noting things.

Restructuring the directory layout

When I started with openwferu I saw the following type of directory structure:

$ tree -d -L 2 --dirsfirst openwfe-ruby/ 
openwfe-ruby/
|-- lib
|   `-- ru
|-- tst
`-- website
    `-- src

Basically a decently structured project however one problem is that this directory structure does not adhere to subversion’s normal directory setup of branches/ tags/ trunk/ . This creates a few problems such as:

1. Force developers to learn a new directory layout convention
2. Makes it difficult to create tags and branches of the project
3. Forces customization of svn tools that rely on this directory structure

After discussing with John on this matter. He agreed we should restructure the directories around to adhere to a typical subversion layout.
After restructuring the codebase it now looks like this:

$ tree -d -L 3 --dirsfirst . 
.
|-- branches
|-- tags
`-- trunk
    `-- openwfe-ruby
        |-- lib
        |-- pkg
        `-- test

Gemification of OpenWFEru

I was about to start up on documenting the codebase again when I realized that OpenWFEru’s release system was basically a shell script. Actually, most of the release tools were small shell scripts to handle tasks for running unit tests, creating a zipfile release, and generating rdoc from the sourcecode.

While this is okay, the Ruby world has built the Gems package management system to handle these problems. So I decided my next task was to bring openwferu into the gems world. This involved RTFM…

Unfortunately, I found the docs on the Gems website pretty weak at explaining the process besides some hand waving and a reference to some build tool called Rake. Luckily, I have a copy of Programming Ruby sitting on my desk here so flipped it open to Chapter 17 on package management with RubyGems and just followed through the example and substituted all relevant parameters with ones that were suitable for OpenWFE. A little bit later I had both a gemspec file and a Rakefile ready. Note that the Rakefile is a superset of the gemspec file (a Gemspec is basically embedded inside the Rakefile and some tasks are added to Rake). I took my shot at trying to generate a gem however failed…

The reason for the failure was based on OpenWFE following the version numbering policies of its java-based cousin (1.7.3pre1-something). No biggie, except the Ruby Gems website explains in detail why you should follow a version policy of major.minor.build (ex. 1.5.4). After discussing this with John, we decided to renumber OpenWFE to 0.9.0 as the API is mostly complete and the base functionality is there. However, there are some details that prevent it from being called a 1.0 release. I’ll let John decide on that.

After renumbering the versions, I ran the rake command listed in Programming Ruby that would generate a gem file (rake pkg/openwferu-0.9.0.gem). Lo and to my surprise, it built the gem all properly. No major fusses. A good portion of this can be attributed to John mostly following ruby conventions of keepign your code inside of lib/ rather than splattered all across the file system. Once nice thing about Rake and the Gemspec is that they are basically Ruby files so anything you can dream up in Ruby can be added into these files to help in customizing a build file. Luckily, for OpenWFE there wasn’t much needed. But it’s a double win as there is a much lower mental overhead in learning how to declare your build configuration without having to context switch between two different syntaxes (I mean you ant).

Now that gems can be easily created I can return to my original activity of trying to add examples and better documentation on using OpenWFE along with an extra activity of figuring out how to get the built gem files on RubyForge.