What is Tracco?

Tracco is an effort tracker for Trello: the purpose of Tracco is to extract and track estimates and actual efforts out of the cards on your Trello boards. All you have to do is add estimates and efforts as comments added on your Trello cards, using a simple conventional format. Tracco will extract, store and aggregate these estimates and efforts to let you mine useful key metrics (e.g. estimate errors, remaining efforts, pair programming frequencies, and so on).

Why Tracco?

Trello is a very good surrogate for a physical team board: it's simple and effective, and it can really help when you have a distributed team. That said, Trello (still) doesn't offer a way to track time estimated and actually spent on cards, though many people are asking for that feature on Trello's development board.

Having that precise need, we defined a simple convention to track estimates and efforts on cards: we use a predefined board member (let's call him 'tracking user') which we sent comments to (we call them 'tracking notifications'), using the comment form available on the card panel.

This 'tracking user' will then receives estimates and efforts notifications, and Tracco will collect and store them. Moreover, a web app is available to properly present card estimates and efforts: Trello Effort App.

More details

To start using Tracco you should have a Trello account, a Trello board and a board member to use as 'tracking user'. You'll also need to know your Trello developer key and generate a proper auth token to have access to the tracking user's notifications. To see how to have these two keys, see the following section.

The Trello API is used behind the scenes to read data from the team board. Tracco uses the awesome Trello API Ruby wrapper for this purpose.

Usage

Tracco is not provided with a built-in viewer for the collected data, so the recommended way to use Tracco is by using Trello Effort App or including the gem in your own viewer app. By the way, this tool can be used as a standalone gem or cloning this git repo.

Installation as a ruby gem

gem install tracco

Installation cloning the repo

git clone git://github.com/xpepper/tracco.git

Then cd in the cloned repo and install all the dependencies with Bundler

cd tracco
bundle install

Then copy the config template

cp config/config.template.yaml config/config.yml

and fill the correct values in the placeholders (see "Where do I get an API key and API secret?" section).

And finally copy the mongoid config template

cp config/mongoid.template.yaml config/mongoid.yml

and fill the correct values for the mongodb environments (see here to have more details).

Full Disclosure: this library is still work-in-progress, so if you find anything missing or not functioning as you expect it to, please open an issue on github.

Requirements

• MRI version 1.9.3+
• mongoDB - macosx users with homebrew will just run 'brew install mongodb' to have mongoDB installed on their machine.
• (optional) rvm is useful (but optional) for development

Where do I get an API key?

Log in to Trello with your account and visit https://trello.com/1/appKey/generate to get your developer_public_key.

Where do I get an API Access Token Key?

To generate a proper access token key, log in to Trello with the 'tracking user' account. Then go to this URL:

https://trello.com/1/authorize?key=<YOUR_DEVELOPER_PUBLIC_KEY>&name=Tracco&response_type=token&scope=read&expiration=never

At the end of this process, you'll receive a valid access_token_key, which is needed by Tracco to have the proper rights to fetch all the tracking notifications sent as comments to the 'tracking user'.

Collecting data from Trello

tracco collect today --environment test # will extract today's tracked data and store on the test db

tracco collect today  # will extract today's tracked data and store on the default (that is development) db

tracco collect 2012-11-1 --environment production  # will extract tracked data starting from November the 1st, 2012 and store them into the production db

Or you may just create a TrelloTracker instance and execute its track method.

require 'tracco'

tracker = Tracco::TrelloTracker.new
tracker.track

Configuration params

Mongo storage configuration

Tracking data collected from Trello are stored in a MongoDB database.

There are two env variables you can set to configure mongodb

• TRACCO_ENV defines which mongodb environment is actually used ("development", "test", "production"). Development is the default environment.
• MONGOID_CONFIG_PATH defines the path to the mongoid configuration file (default is config/mongoid.yml)

A standard mongoid.yml is the following:

development:
  sessions:
    default:
      database: tracco_dev
      hosts:
        - localhost:27017
test:
  sessions:
    default:
      database: tracco_test
      hosts:
        - localhost:27017
production:
  autocreate_indexes: true
  persist_in_safe_mode: true

  sessions:
    default:
      database: tracco_production
      hosts:
        - localhost:27017

Trello configuration params

You can set the Trello's configuration params in three ways. Through the following environment variables (ENV object):

  access_token_key
  developer_public_key
  tracker_username

Passing into the constructor a hash containing the auth values:

tracker = Tracco::TrelloTracker.new(
 developer_public_key: "487635b55e6fe9021902fa763b4d101a",
 access_token_key: "33bed56f2a12a49c9ba1c2d6ad3e2002e11a34358c3f3fe260d7fba746a06203",
 tracker_username: "my_personal_tracker")

tracker.track

Or using the config.yml (which is the actual fallback mode, useful in development mode).

Console

You can open a irb console with the ruby-trello gem and this gem loaded, so that you can query the db or the Trello API and play with them

tracco console

The default env is development. To load a console in the (e.g.) production db env, execute:

tracco console -e production

Estimate format convention

To set an estimate on a card, a Trello user should send a notification from that card to the tracker username, e.g.

@trackinguser [15p]
@trackinguser [1.5d]
@trackinguser [12h]

estimates can be given in hours (h), days (d/g) or pomodori (p).

@trackinguser 22.11.2012 [4h]

will add the estimate (4 hours) in date 22.11.2012.

Effort format convention

To set an effort in the current day on a card, a Trello user should send a notification from that card to the tracker username, e.g.

@trackinguser +6p
@trackinguser +4h
@trackinguser +0.5g

efforts can be given in hours (h), days (d/g) or pomodori (p).

Tracking an effort in a specific date

To set an effort in a date different from the notification date, just add a date in the message

@trackinguser 23.10.2012 +6p

There's even a shortcut for efforts spent yesterday:

@trackinguser yesterday +6p
@trackinguser +6p yesterday

Tracking an effort on more members

By default, the effort is tracked on the member which sends the tracking notification.

To set an effort for more than a Trello user (e.g. pair programming), just add the other user in the message, e.g.

@trackinguser +3p @alessandrodescovi

To set an effort just for other Trello users (excluding the current user), just include the users in round brackets, e.g.

@trackinguser +3p (@alessandrodescovi @michelevincenzi)

Tracking a card as finished (aka DONE)

Sending a tracking notification with the word DONE

@trackinguser DONE

will mark the card as closed.

Moreover, a card moved into a DONE column (the name of the Trello list contains the word "Done") is automatically marked as done.

Database import/export

To export the db you can execute something like:

mongoexport --db tracco_production --collection tracked_cards --out tracco_production.json

To reimport that db:

mongoimport  --db tracco_production --collection tracked_cards --file tracco_production.json

Google Docs exporter

To export all your tracked cards on a google docs named 'my_sheet' in the 'tracking' worksheet, run

tracco export_google_docs my_sheet tracking -e production

The default env is development.

If you provide no name for the spreadsheet, a default name will be used. If the spreadsheet name you provide does not exists, it will be created in you google drive account.

So, running simply

tracco export_google_docs

will create (or update) a spreadsheet named "trello effort tracking" using the development db env.

Keeping your tracking database up to date

You may install a crontab entry to run the trello tracker periodically, for example

SHELL=/Users/futur3/.rvm/bin/rvm-shell
GEMSET="ruby-1.9.3-p385@spikes"
PROJECT_PATH="/Users/$USER/Documents/workspace/tracco"
LC_ALL=en_US.UTF-8

# m h  dom mon dow   command
*/10 * * * *  rvm-shell $GEMSET -c "cd $PROJECT_PATH;  bundle exec tracco collect today -e production" >> /tmp/crontab.out 2>&1

Roadmap and improvements

We develop Tracco using Trello itself.

Contributing

I'd like to pair with anyone wishing to contribute on Tracco. Contact me!

If you'd like to hack on Tracco, start by forking the repo on GitHub:

https://github.com/xpepper/tracco

The best way to get your changes merged back into core is as follows:

1. Clone down your fork
2. Create a thoughtfully named topic branch to contain your change
3. Hack away
4. Add tests and make sure everything still passes by running rake spec
5. If you are adding new functionality, document it in the README
6. Do not change the version number, we will do that on our end
7. If necessary, rebase your commits into logical chunks, without errors
8. Push the branch up to GitHub
9. Send a pull request for your branch

@pierodibello