Idli is a command line interface to bug tracking tools. The goal is simple. To add a bug to a project, you can visit your bug tracker's website and use the web interface.

I (the author) prefer the command line:

$ idli add --title "The frobnicator is broken." --body "The frobnicator does not frobnicate."

Currently idli allows you to talk to github and trac backends.

WARNING: THIS DOCUMENTATION IS INCOMPLETE

Standard python install:

$ git clone [email protected]:stucchio/Idli.git
$ cd Idli
$ python setup.py build
$ python setup.py install

Make sure you have the necessary dependencies installed. If you have python 2.7 or greater, you already have them.

Idli requires the following modules:

argparse
json
urllib, urllib2

Note that argparse comes installed with Python 2.7 or greater, and json with Python 2.6 or greater. There is a good chance you already have these libraries.

To begin, you need to initialize an idli project. The general format for doing this is:

$ cd project_dir
$ idli init BACKEND OPTION1 OPTION2

For example, if the project is hosted on github, you would use:

$ idli init github idli stucchio

This would direct idli set your idli backend to my idli repository.

Some idli commands also require login information:

$ idli config github USERNAME TOKEN

where TOKEN is the github API token (go to https://github.com/account and select "Account Admin").

The idli config command is used to configure global variables, while idli init is used to configure a project.

To add a bug:

$ idli add --title "title of bug" --body "body of bug."
Issue added!

ID: 33
Title: title of bug
Creator: stucchio
Create time: 2010-10-03 14:35:28
Open: True

body of bug.

If the title and body are unspecified, idli will open an editor for you to type them. The specific editor used can be configured via the EDITOR environment variable (note that git uses the same variable).

To tag a bug:

$ ./scripts/idli tag 33 demo
ID: 33
Title: title of bug
Creator: stucchio
Create time: 2010-10-03 14:35:28
Open: True
Tags: demo

body of bug.

Bugs can also be tagged when created with idli add --tags=foo,bar - the resulting issue will have both the tags foo and bar.

To list existing bugs:

$ idli list
ID     date        title                                creator       owner       # comments
11     2010/10/02  warp drive is broken                 kirk                      0
31     2010/10/03  frobnicator is broken                stucchio      stucchio    0
32     2010/10/03  beer in the widgets                  stucchio      homer       3
35     2010/10/03  beer in the frobnicator              stucchio      homer       4
38     2010/10/03  title of bug                         stucchio                  0

To assign a bug:

$ idli assign 11 scotty --message "I need warp drive now."

To comment on an issue:

$ idli comment 11 --body "Keptin, I canna change the laws of physics!"

To list issues owned by you (not supported by all backends):

$ idli list --mine
ID     date        title                                creator       owner       # comments
31     2010/10/03  frobnicator is broken                stucchio      stucchio    0

To list issues with a given tag:

$ idli list --tag=beer
ID     date        title                                creator       owner       # comments
32     2010/10/03  beer in the widgets                  stucchio      homer       3
35     2010/10/03  beer in the frobnicator              stucchio      homer       4

To view a bug in more detail:

$ idli show 11
ID: 11
Title: Frobnicator broken
Creator: stucchio
Create time: 2010-09-21 03:26:57
Open: True
Tags: frobnicator

So very broken.

To resolve a bug:

$ idli resolve 11 --message "Issue resolved by fixing the frobnicator."

Not all features work in all backends. Github, for example, does not support assigning a bug to a user.

Idli can connect to the bug tracker at github. To use, first you need to configure idli with your github login information:

$ idli config github USER TOKEN

Here, USER is your username and TOKEN is your github API token. The TOKEN can be accessed by logging in to github, proceeding to https://github.com/account and selecting "Account Admin".

This need only be done once per computer.

To initialize a github project:

$ idli init github REPO OWNER

Here, REPO is the name of the repository (e.g., 'idli') and OWNER is the github username of the project owner (e.g., 'stucchio').

If you wish to use a separate USER/TOKEN pair for a specific project, after calling idli init, you can use:

$ idli config --local-only USER TOKEN

This will set the USER/TOKEN for the current project only.

Trac is much the same is github, but with slightly different parameters:

$ idli config trac USER PASSWORD
$ idli init SERVER PATH

Idli can be used with trac, but this requires the xmlrpc plugin for trac to be enabled.

First, the xmlrpc plugin for trac must be installed:

$ easy_install -Z -U http://trac-hacks.org/svn/xmlrpcplugin/trunk

The website for the plugin is here: http://trac-hacks.org/wiki/XmlRpcPlugin

Then it must be enabled. This can be done by adding the following to your trac.ini file:

[components]
tracrpc.* = enabled

Lastly, xmlrpc permissions must be given to authenticated users:

$ trac-admin TRAC_DIRECTORY permission add authenticated XML_RPC

New backends can be added to idli by subclassing idli.Backend. For example, the GithubBackend has the following general structure:

class GithubBackend(idli.Backend):
    name = "github"
    config_section = "Github"
    init_names = { "repo" : "Name of repository",
                   "owner" : "Owner of repository (github username).",
                   }
    config_names = [ ("user", "Github username"),
                     ("token", "Github api token. Visit https://github.com/account and select 'Account Admin' to view your token.")
                     ]

The init_names and config_names parameters are used to create the arguments for idli init and idli config respectively. These parameters can be retrieved using self.get_config(name) (i.e., in a GithubBackend method, one can call self.get_config("repo") to get the name of the reposuitory).

Then, various specific methods must be build:

def add_issue(self, title, body): #Adds issue
    ...Implementation details...

def issue_list(self, state=True): #Returns a list of idli.Issue objects - state is whether they are open or closed
    ...Implementation details...

etc. For a full listing, see the file idli/__init__.py. Any method which raises an IdliNotImplementedException must be overridden (if possible).

To report errors to the user, you should raise an idli.IdliException("error message") from within the backend:

def issue_list(self, state=True):
    ...Implementation details...
    raise idli.IdliException("Github hates us!")

...More details...