Extending an open-source software system

In this blog entry I post about my experience extending the Hale-aloha-cli-grads open-source software system. 

Introduction and Background

In my last post I reviewed and evaluated the open-source software system named Hale-aloha-cli-grads, in the context of the three prime directives of open source software development, issue driven project management, and continuous integration. In this post I will relate my experience adding functionality to this system and collaborating with my partner, Zach Tomaszewski.  

Here I re-introduce some background information to set the context for this blog post.

Hale-aloha-cli-grads
The Hale-aloha-cli-grads system under review is an open-source project that implements a command line interface (CLI) for WattDepot, created by Andrea Connell, Leo DeCandia, and Sergey Negrashov. It retrieves and displays energy and power data for the four Hale Aloha residential towers at the University of Hawaii Manoa campus.

Hale-aloha-cli-jz
The Hale-aloha-cli-jz system is an open-source project that also implements a command line interface (CLI) for WattDepot, created by my partner Zach Tomaszewski and myself. This software project implements the same specifications as Hale-aloha-grads, and for this endeavor, each group is extending the others' system.

WattDepot
The wattdepot open-source project developed at the University of Hawaii, is a collection of technologies and tools for collecting and storing data from electricity meters for smart grid research and experimentation. 

The 3 Prime Directives of open-source Software Development
To refresh your memory, and for the purposes of relating my experience, the three prime directive of open-source software development are summarized as follows:

1. Does the system accomplish a useful task? 
2. Can an external user can successfully install and use the system?
3. Can an external developer successfully understand and enhance the system? 

By extending Hale-aloha-grads, I hope to determine more accurately whether or not it satisfies prime directive 3. In my last post I downloaded, installed, and reviewed the code. Now, actually extending the code should provide a more accurate answer to prime directive 3.

Issue-Driven Project Management and Continuous Integration
Please see my previous blog entry to gain an understanding of Issue Driven Project Management and Continuous Integration.
Adding Functionality to the System with 3 new Commands
I will relate important aspects of our experience extending an open-source software system: the build process, developer contribution, documentation, testing, and software quality.  
My partner and I added the new functionality outlined below. In all commands below,  [tower | lounge] defines a source.

Commands and command line argument specification

set-baseline [tower | lounge] [date]

• This command uses date as the "baseline" day for the source.  
• The date is optional, in YYYY-MM-DD format, and defaults to yesterday. 
• When run, the system obtains and saves the amount of energy used during each of the 24 hourly periods of that day for a given source and date,  defining a baseline for that source.

monitor-power [tower | lounge] [interval]

• This command prints out a timestamp and the current power for the source every interval seconds.  
• Interval is optional and defaults to 10 seconds. 
• Entering a carriage return stops the monitoring process and returns the user to the CLI command loop.  

monitor-goal [tower | lounge] goal [interval]

• When run, this command prints out a timestamp, the current power being consumed by the source, and whether or not the source is meeting its power conservation goal.  
• Goal is an integer between 0 and 99 that defaults to 5.  It defines the percentage reduction from the baseline for this source at this point in time.
• Interval is optional and defaults to 10 seconds, and defines how often to retrieve energy data and display it to the user.
• If the monitor-goal command is invoked without a prior set-baseline command for that source, it is an error.
• Entering a carriage return stops the monitoring process and returns the user to the CLI command loop.

Some example runs and output for new commands:

set-baseline Ilima

Setting baseline values for Ilima on 2011-12-11
hour  energy
0     32.2 kWh
1     30.2 kWh
2     27.0 kWh
3     25.3 kWh
4     24.2 kWh
5     23.6 kWh
6     22.7 kWh
7     20.4 kWh
8     20.2 kWh
9     20.8 kWh
10    21.6 kWh
11    22.2 kWh
12    22.8 kWh
13    24.3 kWh
14    25.5 kWh
15    26.1 kWh
16    26.7 kWh
17    29.3 kWh
18    31.1 kWh
19    33.0 kWh
20    34.8 kWh
21    36.4 kWh
22    36.6 kWh
23    36.2 kWh

monitor-power Mokihana 4

Querying Mokihana for current power every 4 seconds. 
(Press Enter to stop.)


Most Recent Data     Power Consumption (kW) 
 16:51:20                 25.21
 16:51:20                 25.21
 16:51:20                 25.21
 16:51:20                 25.21
 16:51:20                 25.21
 16:51:20                 25.21

monitor-goal Ilima 5 3

Querying Ilima for current power every 3 seconds. 
(Press Enter to stop.)


Timestamp  | Power (kW) | Baseline (kW) | Base Hour  | Goal (kW)  | Goal met? 
 16:47:12     27.77        26.75           16-17        25.41        no        
 16:47:12     27.77        26.75           16-17        25.41        no        
 16:47:12     27.77        26.75           16-17        25.41        no        
 16:47:12     27.77        26.75           16-17        25.41        no 

Extending the System

Issue-Driven Project Management and Continuous Integration

Using Google Project Hosting Issues, Zach and I were able to effectively plan and manage our efforts following the practices of issue driven project management. Commits were done frequently. We broke the work down into tasks. We worked on different tasks at the same time, different tasks at different times, and to a lesser extent, similar tasks at the same time (for example, each of us contributing to the same Java class or JUnit test case).

As far as continuous integration using Jenkins, we had two failed Jenkins builds because I forgot to make sure the system passed the verify target before committing. 

In addition to using Issues in Google Project Hosting, we made use of informal emails and phone conferencing to collaborate and take the place of face-to-face meetings. We had no physical meetings, yet easily accomplished our goals. There was no confusion about tasking and no commit conflicts.

Adding new Commands

Once we got a handle on the existing code, we felt it was inferior to our implementation by a good margin. This was mostly in terms of (very) poor method naming, and overly complex interaction between methods, within methods, and not-so-great test cases.

Although we originally were going to to divide the work with me implementing SetBaseline and MonitorPower, it went the other way with Zach implementing MonitorPower, MonitorGoal and me implementing SetBaseline.

Adding new Test Cases


The Test cases printed a lot of output to the console, and "fake" objects were used for many of the test cases. Since we added our own new tests for the new commands, I did not spend an excessive amount of time analyzing the existing tests, but simply reviewed them. 

Cleaning up the User Interface

The user interface did not meet the specifications outlined for the original project. In particular:

• The help message is printed after every command
• There is not enough white space and command output is difficult to read since it is mixed in with the help text
• Help and quit are not displayed in the list of available commands
• Pressing the return key causes an “Invalid Command” message
• Every run of the system causes a “looking for commands” message and displays the commands found
• There is no command line prompt, just a blinking cursor displayed on an empty line

Taken together, these behaviors made the system 'clumsy' to use. It was rather easy to locate these behaviors in the code and improve upon them. In my opinion, the running system is now easier to use: there is a command line prompt, it is easier to see the output of each command, and it more closely follows the principle of "least astonishment" for any user of the system. Now, help is displayed when you ask for it, the help text makes good use of white space, and the return key (alone) displays the system prompt again, instead of an error message.

Finishing up


I modified the existing wiki pages, and added a new wiki page that covered the new commands. We created a distribution using "ant -f dist.build.xml" and added this to the downloads page of the Google project hosting page for the project.  This zip file can be downloaded to evaluate prime directives 1 and 2.  I made it clear in the wiki's that there are 2 downloads, one for the previous version, and one for the latest version.

Conclusion

Although in my last blog I stated from review and inspection that the system does satisfy prime directive 3, I must say it was a bit more of a struggle than anticipated, and I learned that actually extending the system gives a more accurate assessment of whether or not a system meets prime directive 3. I was a lot more 'attached' to our own implementation of this system (Hale-aloha-cli-jz), however, I was able to get past that feeling, and get on with the task at hand.

Given our collaboration constraints, time constraints, and other commitments, I am happy with the outcome and quality of the software we developed in a relatively short time.