One problem confronting new developers is how to get traction, given that Hackystat is too big a system to simply read all of the source code and internalize before getting started. Fortunately, successful completion of many typical development tasks require a fairly narrow "slice" of understanding through the system. Even so, the novice developer can still have trouble identifying the appropriate slice to understand, and what resources should be looked at to facilitate this understanding. This section takes two common development tasks: developing a new sensor, and developing a new reduction function, and lists the sequence of subtasks that a new developer to Hackystat might follow in order to accomplish the overall task.
Let's say you are a brand new to Hackystat development, and your organization uses a tool for which there is not currently a Hackystat sensor. What would you need to do to make this sensor available to your organization?
To begin, you must become familiar with the way sensors currently work from the user perspective. To do this, you should register with the public server, download HackyInstaller, download some sensors, and send some example data to the public server. Documentation for this is available in Chapter 2, Client-side configuration: Tool sensor installation, Chapter 3, Server-side configuration: User account registration and preferences, and Chapter 4, Collecting and analyzing process and product measures for Java systems using Ant. After completing this, you should have a good sense for how sensors work in general and which sensors are close in behavior to your needs.
Once you are familiar with sensor operation using the public server, the next step is to create a local development environment for your sensor implementation work. To do this, you should first download the Hackystat software sources from its Subversion repository, as documented in Chapter 8, Hackystat server installation.
Once you have successfully downloaded, installed, and tested a local server, you should become more familiar with the build environment by reading Chapter 13, Anatomy of the Hackystat build system. This will help you to understand the Ant targets used by developers to build and test the system, as well as various quality assurance tools such as Checkstyle that are available.
Now you are ready to develop your sensor. You can begin by reading the documentation on sensor development in Chapter 17, Designing sensors. This chapter discusses some of the basic strategies for sensor design, including the use of XSL and the XmlData sensor, Java-based sensor implementation, and sensors for other programming languages and environments. If there is a public sensor that is similar in spirit to the sensor that you need to develop, then it is certainly useful to study the implementation of that sensor in detail.
If you find you cannot use the XSL/XmlData approach to sensor development, then you will probably need to learn more about the SensorShell, Hackystat's "middleware" system for sensor data transmission between clients and server. Chapter 16, The SensorShell provides details about the SensorShell.
If you find that your sensor is going to generate a new form of data unlike any of the current Sensor Data Types, then you will need to define a custom SDT along with your sensor. Chapter 15, Designing sensor data types provides details on that process.
If your sensor's implementation turns out to be nothing more than an XSL stylesheet, and if you are not interested in making it available as a public module, then you may not need to package it as a Hackystat module. In the case of more complicated sensors, it will be useful to create a Hackystat module to encapsulate the implementation. Chapter 14, Creating new Hackystat modules provides information on how to create a Hackystat module to hold your sensor code.
It is typically quite helpful to provide documentation about your sensor to others. Hackystat provides a documentation framework based upon DocBook that enables your sensor documentation to be integrated into the rest of the documentation and appear in the Reference Guide. Chapter 18, Writing documentation provides details on writing your own documentation.
At anytime during the implementation process of your new sensor, you may find it useful to request advice from other Hackystat developers by subscribing to, and sending email to the hackystat-dev-l mailing list. Instructions on subscribing are found in Section 12.2, “Mailing lists”. You can include a high level description of your sensor design, or even pointers to the source code. Consultation with the Hackystat developer community can often significantly speed the successful implementation of your sensor.
A second common extension to Hackystat is the creation of a new reduction function. In this case, your have found that your organization would like to display a trend line using Software Project Telemetry, but no reduction function exists to support the kind of metric data that you want to display. Unlike sensor development, which is primarily a "client-side" task, creation of a new reduction function is a "server side" task. Let's look at how you might proceed in this form of development scenario.
To begin, you must become familiar with the way reduction functions currently work from the user perspective. To do this, you should begin by registering with the public server, downloading HackyInstaller, downloading some sensors, and sending some example data to the public server.. Documentation for this is available in Chapter 2, Client-side configuration: Tool sensor installation, Chapter 3, Server-side configuration: User account registration and preferences, and Chapter 4, Collecting and analyzing process and product measures for Java systems using Ant.
Once you have populated the public server with some sample data, you should experiment with the current set of reduction functions to familarize yourself with their operation. You will need to start by understanding how reduction functions are part of the overall Telemetry framework, which also includes Streams, Charts, Reports, and Y-Axis constructs. Chapter 5, Software Project Telemetry: Understanding the dynamics of software development provides an introduction to all of the telemetry constructs. Once you have finished with this work, you should be comfortable with the use of reduction functions.
The next step is to create a local development environment for your reduction function implementation work. To do this, you should first download the Hackystat software sources from its Subversion repository, as documented in Chapter 8, Hackystat server installation.
Once you have successfully downloaded, installed, and tested a local server, you should become more familiar with the build environment by reading Chapter 13, Anatomy of the Hackystat build system. This will help you to understand the Ant targets used by developers to build and test the system, as well as various quality assurance tools such as Checkstyle that are available.
Now you are ready to develop your reduction function. You can begin by reading the documentation on reduction function development in Chapter 23, Software Project Telemetry: Defining Reduction Functions and Filter Functions. This chapter presents the "anatomy" of reduction functions. If there is an existing reduction function similar in spirit to the one you need, you should certainly study its implementation.
In most cases, you will need to package your reduction function in a Hackystat module. Chapter 14, Creating new Hackystat modules provides information on how to create a Hackystat module to hold your sensor code.
It is typically quite helpful to provide documentation about your reduction function to others. Hackystat provides a documentation framework based upon DocBook that enables your documentation to be integrated into the rest of the documentation and appear in the Reference Guide. Chapter 18, Writing documentation provides details on writing your own documentation.
At anytime during the implementation process of your new reduction function, you may find it useful to request advice from other Hackystat developers by subscribing to, and sending email to the hackystat-dev-l mailing list. Instructions on subscribing are found in Section 12.2, “Mailing lists”. You can include a high level description of your reduction function design, or even pointers to the source code. Consultation with the Hackystat developer community can often significantly speed the successful implementation of your reduction function.
As you can see, there are many commonalities to development, regardless of how you are extending Hackystat. In all cases, it helps to begin by understanding related mechanisms from the User perspective. You will always need to create a local development environment. Then, refer to the specific documentation chapters related to your task. Finally, you will often need to package your addition in a new module, and write documentation about it. The Hackystat development community is always available to help you with issues.