Software versions, documentation, and the PAIN

When working on a piece of software using a framework or an API, the first source of help to rely on is the official documentation. As development on that code base continues, so does the documentation that changes accordingly. Sadly this is not always the case!!

At the time of this post, the latest stable release of the ubiquity project is version 0.54  and the version pulled from mercurial is 0.55pre8. I was trying to write an enhancement to provide feedback to a command's author. My testing environment had the latest stable version, and as the ubiquity wiki is under 0.5, I assumed it matches my currently running version. At the end of the wiki, a link is provided with the documentation of the CmdUtils library, containg the command CmdUtils.getCommand(id).

Such a command is very helpful as it returns the object representing the command matching the given id. Thus, details about the command's author could be obtained, and hence sending to them feedback. Being very excited about this, I gave it a test, and to my shock nothing worked. Even to my bigger surprise, firebug that is used for debuging ubiquity commands showed CmdUtils.getCommand is not a function.

This caught curiosity, so I opened the ubiquity extension's installation folder, and took a look at the "modules/cmdutils.js" file. With no surprise, the file did not contain the CmdUtils.getCommand function.

At the same time, Abdallah El Guindy was working on the same enhancement, reached the same conclusion, but had the function correctly working. When I asked about his running ubiquity version, it as the latest development version 0.55pre8. After taking and installing that version of the code, the "modules/cmdutils.js" file was the one matching the current online documentation.

Having the correct version number attached to the online documentation, would have saved development time and confusion. Such a problem is not restricted to the ubiquity project, but is also seen in other frameworks or APIs. The main lesson learned here, is that one has to be very careful during development, and not give up easily on finding the root of the problem.

On a small side note, this same problem with ubiquity 0.54 is also in 0.55pre7 (the current latest beta). So the CmdUtils.getCommand(id) is a brand new addition to the code base.