: Documentation

How CIA Works

This page gives a more detailed view of CIA's workings than the one presented on the introduction page.

This document is very outdated.

Background

CIA's goal is to track open source projects in real-time. Mailing lists can be slow, and are often ignored. For CIA to be a valuable tool in collaborative software development, the messages have to get from the version control system to the developers as fast as possible.

There are a few projects for which CIA has filter scripts that it uses to gather information from mailing lists. In the vast majority of projects, however, there is a script installed in the revision control system that sends commits directly to CIA.

In CIA's first incarnation, these client scripts sent email to the CIA server with a pre-formatted commit message. This made the server simple, but it had several problems:

  • Each project was free to define their own colors and formatting for the commit message. While this extra freedom could be helpful, it made the central #commits IRC channel look a bit chaotic.
  • While it was easy to present the commit messages in IRC, you couldn't really do anything else with them. Even displaying them on the web with a white background and proportional font was awkward.
  • The client scripts' formatting capabilities evolved, but inevitably many projects didn't upgrade. At the time of this writing, some projects are still using the very first CIA client script, which was very error prone and only displayed the first line of the log message and the author.

With the CIA rewrite then came XML commit messages. Now a CIA client can send raw information about a commit (or potentially any other event) to the server, over email or XML-RPC, where it is then formatted into different mediums as appropriate. Projects have no explicit control over the presentation of their commit messages. Instead, the messages' end user is in control of the format, be it a web interface or an IRC channel.

Components

This section describes all the important components CIA uses to bring messages from your project to their destination.

  • Client Script

    This is a relatively simple and self-contained script that must be able to format messages from your project in a way CIA can understand, then deliver them to CIA. The only requirement CIA has of a client script is that it can generate well-formed and valid XML messages. Client scripts have been written for many different version control systems and in many programming languages.

  • Message

    CIA still supports the old format used before XML messages were implemented, but all projects are encouraged to only use the new format. An XML message consists of an envelope that holds general information about the message's source, and a body which may contain a commit message, automated build results, bug tracker updates, or anything else. This document focuses on messages containing commits to a version control system.

    FIXME: There should be a link here to a page with example messages and the XML schema

  • Server

    The CIA server is responsible for receiving messages and delivering them to interested parties. This may include IRC bots, logging systems, statistics, or anything the server has a URI handler registered for.

    In this implementation, the server is one process written using Python and Twisted that runs an HTTP server for the web interface and XML-RPC, and forms outgoing connections for IRC bots and XML-RPC notification.

  • Ruleset

    The CIA server has a list of Rulesets it uses to filter, format, and direct each message. The ruleset is a usually small piece of XML that gives a tree of commands used for filtering and formatting the messages. If a message passes the ruleset's tests, it is then delivered to the URI specified by the ruleset.

    FIXME: Link to a more in-depth explanation of the ruleset language, with examples and again a reference to the schema

  • URI

    The destination for a message to be delivered to after passing a ruleset is specified as a Universal Resource Identifier. Several nonstandard URI schemes are used to describe destinations such as IRC channels, stats targets, or even XML-RPC methods.

    FIXME: again, this needs to link to examples