This is the Bicho User Manual, v1.1.

Content
*******

1.- About Bicho
2.- Requirements
3.- Installation
4.- Usage
5.- Credits



1.- About Bicho:
		-------------

Bicho is a Bug Tracker System Analyzer. It extracts information about bugs,
such as: ID, priority, resolution, status, comments, descriptions,
changes, attachments and so on. It then puts them in a database in order to
let you use that information to study and analyze it.

Bicho is capable of analyzing the following BTSes (Bug Tracker Systems):

* Apache
* Bugzilla
* SourceForge (Allura)
* Redmine
* GitHub
* Google Code (out-of-date)
* JIRA
* Launchpad




2.- Requirements:
		--------------

Bicho needs some libraries, such as:

* Storm: Storm is an object-relational mapper (ORM) for Python
  developed at Canonical. The project was in development for more than a
  year for use in Canonical projects such as Launchpad and Landscape
  before being released as free software on July 9th, 2007
  (https://storm.canonical.com/)

* Beautiful Soup: Beautiful Soup is a Python HTML/XML parser designed for
  quick turnaround projects like screen-scraping
  (http://www.crummy.com/software/BeautifulSoup/)

* Python (>2.6)
* python-mysqldb



3.- Installation:
		---------------

Bicho depends on several other packages, including Storm, Beautiful Soup, dateutil, and (if you are working with a Launchpad bugtracker) launchpadlib. Details for a few of those requirements are below.

Installing Requirements: Storm

Step 1: Download Storm

Storm 0.15 and above will work. The download page of Storm is: 
https://launchpad.net/storm

$ wget https://launchpad.net/storm/trunk/0.20/+download/storm-0.20.tar.bz2

Step 2: Decompress and unpack

$ bunzip2 storm-0.20.tar.bz2
$ tar xvf storm-0.20.tar

Step 3: Install it

$ sudo python setup.py install

Steps 1-3: Alternative

If you prefer, you can download, unpack, and install Storm in one step with

$ pip install storm

Step 4: Test it

Start up a Python interpreter by typing "python" or "ipython" at a terminal. 

> import storm

If you do not get a message telling you that storm does not exist, the
library was installed succesfully.



Installing Requirements: Beautiful Soup

Step 1: Download Beautiful Soup

Bicho works with Beautiful Soup 3.

$ wget http://www.crummy.com/software/BeautifulSoup/download/BeautifulSoup.tar.gz

Step 2: Decompress and unpack

$ tar xvzf BeautifulSoup.tar.gz

Step 3: Install it

$ sudo python setup.py install

Steps 1-3: Alternative

If you prefer, you can download, unpack, and install Beautiful Soup in one step with
a package manager, with one of the following commands:

$ apt-get install BeautifulSoup

or

$ easy_install BeautifulSoup

or

$ pip install BeautifulSoup

Step 4: Test it

Start up a Python interpreter by typing "python" or "ipython" at a terminal.

> import BeautifulSoup

If you do not get a message telling you that BeautifulSoup does not exist, then the
library was installed succesfully.



Installing Bicho:

Step 1: Download Bicho

For the latest released package, Bicho 0.9:

$ wget https://github.com/downloads/MetricsGrimoire/Bicho/bicho_0.9.tar.gz

For the development version:

$ wget https://github.com/MetricsGrimoire/Bicho/tarball/master

Step 2: Unpack/Decompress package

$ tar xzvf [name of downloaded file]

Step 3: Installing it

$ sudo python setup.py install

Step 4: Test it

At a terminal, type:

$ bicho --help
Usage: bicho [options] [URL]

It extracts data from bug tracking systems from a project given

Options:

   -h, --helpPrint this usage message.
   -t, --type           Type optionsf bug tracking system (sf|bg)
SourceForge or Bugzilla
   -p, --pathPath where downloaded URLs will be stored (/tmp/bicho/)

Database input specific options:
   --db-driver_inInput database driver [sqlite|mysql|postgres] (None)
   --db-user_inDatabase user notame (None)
   --db-password_inDatabase user password (None)
   --db-databasetabase_inDatabase name (None)
   --db-hostname_inName of the host wherere database server is running
(None)
   --db-port_inPort where the databasetabase server is running (None)

Database output specific options:

  --db-driver_outOutput database driver [sqlite|mysql|postgres] (mysql)
  --db-dbuser_outDatabase user name (None)
  --db-password_outDatabase user postgresassword (None)
  --db-database_outDatabase name (None)
  --db-hostname_inName_outName of the host where database server is
running (localhost)
  --localhostdb-port_outPort where the database is (3306)


Values found in the config file 'bicho.conf' are used as default values.
If config file is not found, all parameters are required except:

    if url is given:
        Database input parameters are not required
    else:
        Database input parameteres are required.



4.- Usage:
		-------

As you can see, if you execute "bicho --help" command, Bicho has several
parameters. This section is aimed to show you how to use Bicho to
analyze a Bugzilla BTS or a SourceForge BTS.

Analyzing a Bugzilla BTS:

NOTE: It is important to note that you have to create an empty database that
Bicho is going to use before executing the application.

$ mysqladmin -uuser -ppassword create database_name

$ bicho -t bg --db-user_out="user" --db-password_out="password"
--db-database_out="database_name" "URL_project_BTS"

Analyzing a SourceForge BTS:

NOTE: It is important to note that you have to create an empty database that
Bicho is going to use before executing the application.

$ mysqladmin -uuser -ppassword create database_name

$ bicho -t sf --db-user_out="user" --db-password_out="password"
--db-database_out="database_name" "URL_project_BTS"



5.- Credits:
    ---------

Daniel Izquierdo Cortazar <dizquierdo@libresoft.es>
Francisco Rivas <frivas@libresoft.es>

