Skip to content
This repository

Home 

tomkersten edited this page · 25 revisions

Pages 1

Clone this wiki locally

QuickStart

Installation

The official gem is available on RubyForge:

sudo gem install codefumes

However, if you prefer to use the Github gem you can also do:

sudo gem install cosyn-codefumes

Usage

Examples below assume you have required & included the codefumes gem:

require 'codefumes'
include CodeFumes

Working with Projects

# Point all requests to the "test" site since we don't care about this content
CodeFumes::API.mode :test

my_project = Project.new(:public_key => "sample_project")
my_project.save       # => true
my_project.api_uri    # => "http://test.codefumes.com/api/v1/xml/projects/sample_project.xml"
my_project.public_key  # => "sample_project"
my_project.private_key #=> "3ed56635dcb9bd8a8254b54b959ce8f74cb2f9ff"
# See documentation for other methods/attributes available

# Now let's find the project we just saved
find_it = Project.find(my_project.public_key)
find_it.api_uri      # => "http://test.codefumes.com/api/v1/xml/projects/sample_project.xml"
find_it.private_key  # => "3ed56635dcb9bd8a8254b54b959ce8f74cb2f9ff"

Working with the CodeFumes config file

# Save the project to the CodeFumes config file
ConfigFile.save_project(my_project)

# Retrieve it later from that file
project_info =  ConfigFile.serialized[:projects][:sample_project]
=> {:api_uri=>"http://test.codefumes.com/api/v1/xml/projects/sample_project.xml",\
    :private_key=>"3ed56635dcb9bd8a8254b54b959ce8f74cb2f9ff",\
    :short_uri=>"http://test.codefumes.com/p/sample_project"}
# The private key will be used whenever updating the project, or sending up data associated
# with it and the URI keys tell other libraries/tools where to interact with the project.

Sending up commit information in a Payload

Some of this may seem a bit verbose at first. The good news is that the SourceControl class in the codefumes_harvester gem wraps all of this up so you never have to deal with it (unless you’re into that).

payload = Payload.new(:public_key => :sample_project,
               :private_key => "3ed56635dcb9bd8a8254b54b959ce8f74cb2f9ff",
                :content => {:commits =>
                      [{:identifier => "f28aa155ea68ad7606e01fd46b97753062292043",
                        :affected_file_count=> 2}]
                })

payload.save   # => true

# Save a custom attribute to the same commit (using a separate payload, in this example)
payload = Payload.new(:public_key => :sample_project,
                   :private_key => "3ed56635dcb9bd8a8254b54b959ce8f74cb2f9ff",
                    :content => {:commits => 
                         [{:identifier => "f28aa155ea68ad7606e01fd46b97753062292043",
                           :custom_attributes => {:my_custom_attribute => 39}}]
                    })
payload.save   # => true

Retrieving Commit data

Note: Since all data is sent up in Payload requests, Commits are read-only.

commit = Commit.find("f28aa155ea68ad7606e01fd46b97753062292043")
commit.affected_file_count # => "2"
commit.custom_attributes   # => {:my_custom_attribute=>"39"}

Component Overview

Codefumes.com has 3 primary components: Projects, Commits, and Payloads (the CodeFumes config file gets “honorable mention” as well). Understanding how these components tie into one another will likely help you to effectively utilize the service and associated tools.

Projects.

A “project” loosely maps to a source code repository. Generally speaking, a project is set up by using the harvest_repo_metrics executable (shipped with the codefumes_harvester gem). Executing that script will set up a new project on CodeFumes.com and send up information about each commit in the repository. If a project is saved, an entry is made in the CodeFumes ConfigFile, which contains the information required to update the project (the project’s API URI, public key, private key). Subsequent executions of harvest_repo_metrics will automatically send new repository information up to the same CodeFumes project.

NOTE: Linking a repository to a CodeFumes project was done in the “simplest case” scenario…a repository is linked to only one CodeFumes project (versus, say, a project for every branch in a repository). This could be modified if there is a demand for branch-specific projects in the community. During the development of the gems and code associated with the CodeFumes.com website, the majority of metrics were sent up from our continuous integration server. We never found the need to modify this model, as we weren’t concerned with long-term tracking on branches that would likely not be “long-term”.

The CodeFumes config file

The information required to find, update, and associate content with a project can (read: should always) be stored in the standard CodeFumes config file (For those interested, this “information” includes each project’s public key, private key, the API URI and the “short URI” for accessing the project). The ConfigFile class wraps convenience methods up to interact with this file so developers should not have to be concerned with the file structure, location, and other mundane tasks around interacting with the file and its contents.

Commits

Commits are the center(s?) of the universe, as far as CodeFumes is concerned. They bind your code with a point in time, giving you a concrete point at which you can associate other data points. A commit has standard attributes which are supported “across the board”, such as the author, timestamp, commit message, et cetera. In addition to this, users are able to associate “custom attributes” to a commit, which are essentially key-value pairs of “attribute name” and “attribute value”.

NOTE: See the gem’s documentation for comprehensive list of standard attributes.

Commits are uniquely identified by the “identifier” provided. The timeline of a repository is defined by the “parent” identifier(s) specified in the list of commit attributes. One things to note is that attributes can be associated with a commit identifier at any time, regardless of whether or not the commit has been positioned in the repository timeline. For example, if you send up your repository metrics from a continuous integration server, but want to associate some metric with a commit before it has been pushed up to the CI server…it’s OK…just send it up. Everything will merge together and it will show up in the project timeline when the parent identifiers for that commit have been provided.

Payloads

Payloads provide a simple interface for sending data to a project, particularly when large amounts of data need to be delivered. The Payload class provides a #prepare method, which will chunk up a large collection of data into payloads the application server can handle. For example, if you had a repository with 600 commits, the serialized version of that repository’s history will likely be more than the application server’s request limit, which is a little over 8,000 bytes (this is a standard POST, not a Multi-Part. Multi-Part POST requests are not supported at this time).

Where to go from here

Something went wrong with that request. Please try again.