Developing EKG

Reporting Bugs

In order to report bugs appropriately please make sure to do the following.

• File a bug report on Fedora Hosted
• Please make sure to tag it to the version you are using. If a tag is not available, note it directly in the bug report, and an admin will fix it for you.
• If you installed EKG from an RPM, include the RPM version
• If you are running directly out of the development source code, include the hash code from git
• Include your terminal session, including any stack traces
• Save a copy of your Sqllite database
• Compress (tarballs please) and save a copy of your working directory, so we can check the cache EKG builds. Since most documents are text, compression can save considerable bandwidth and time.

Setting up Development

EKG uses setuptools so setting up an environment with virtualenv is not difficult.

$ sudo yum install python-virtualenv python-setuptools-devel
$ git clone ssh://git.fedorahosted.org/ekg.git ekg
$ cd ekg
ekg $ virtualenv --no-site-packages ~/virtualenvs/ekg
ekg $ source ~/virtualenvs/ekg/bin/activate
(ekg) ekg $ python setup.py develop
(ekg) ekg$ cd ..
(ekg) $ mkdir ekg-run
(ekg) $ cd ekg-run
(ekg) ekg-run $ <run ekg commands here>

Code Overview

TODO: Turn this into something that can be generated with Sphinx and link/embed it.

The data model behind EKG is broken up into three distinct components, Streams, Sources and Facts. A Stream is a continous source of data where new data can constantly be found. A Source is a concrete chunk of data that can be downloaded and cached in one piece. A fact represents a single activity, comment or otherwise contribution on a stream. A stream has multiple sources, a source has multiple facts.

In order to understand this more concretely, these objects can be subclassed into more concrete objects. The following table shows the relationship between these abstract types and possible real world objects.

Stream	Source	Fact
Mailing List	Mbox (containing, for ex. one month's messages	Email (a single posting by a user
Git Repository	Mbox of Patches	Single Commit
Wiki	Page	Edit
Wiki	Archive of activity	Edits
Bug Tracker	Archive of Activity	Comments and changes
Bug Tracker	Bug Report / Ticket	Comments and changes
IRC Logs	Day / Week / Months log	Line of text

Note: Certain topics are repeated because the model is not fully yet explored. Both are valid interpretations based on the flow of the commmunity. Analysis in graph runs on top of Facts primarily in any case.

Creating commands

EKG can expose commands to the command line to give access to various functionality. All commands to ekg are prefix with a hyphen automatically. To expose your own commands, use the command decorator from the ekg.commands module. An example.

from ekg.commands import command

@command
def take_a_long_walk_off_a_short_pier():
    print 'splash!'

This would yield an executable ekg-go-take-a-long-walk-off-a-short-pier. All underscores are converted to hyphens. This point could not be underscored nor underlined more.

Playing Appropriate Music

Loud Music is Good and Good Music is Loud. Good and Loud music are necessary prerequisites for working on EKG.