Build Status Code Climate

Trello Effort Tracker

What is Trello Effort Tracker?

The purpose of this tool is to extract and track estimates and actual efforts on Trello cards. You simply notify all of your estimates and efforts tracked on your Trello cards using a conventional format. Trello Effort Tracker will extract and store these estimates and actual efforts to let you mine useful key metrics (e.g. estimate errors, remaining efforts, pair programming frequencies, and so on).

Why Trello Effort Tracker?

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 does not (still) offer a way to track time estimated and actually spent on cards, though many people ask 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 special notifications to (we call them 'tracking notifications'). This 'tracking user' will then receives estimates and efforts notifications, and Trello Effort Tracker will collect and store them. Moreover, a web app will be soon available to properly present card estimates and efforts (we're working on it).

More details

All you need to have to start using Trello Effort Tracker is 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 trackinguser'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. Trello Effort Tracker uses the awesome Trello API Ruby wrapper for this purpose.

Usage

This tool can be used as a standalone gem or cloning this git repo.

Installation as a ruby gem

gem install trello_effort_tracker

Installation cloning the repo

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

Then cd in the lib and copy the config template

cd trello_effort_tracker
cp config/config.template.yaml config/config.yml

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

Then 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).

Then run bundle to get all the required gems:

bundle install

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

  • 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/connect?key=<YOUR_DEVELOPER_PUBLIC_KEY>&name=Trello+Effort+Tracker&response_type=token&scope=read,write&expiration=never

At the end of this process, you'll receive a valid access_token_key, which is needed by Trello Effort Tracker to fetch all the tracking notifications sent to the 'tracking user'.

Usage

The best way is to use one of the rake task defined, e.g.

rake 'run:today[test]' # will extract today's tracked data and store on the test db

rake run:today  # will extract today's tracked data and store on the default (that is development) db

rake 'run:from_day[2012-11-1, 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 'trello_effort_tracker'

tracker = 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

  • MONGOID_ENV defines which mongodb env is actually used (development, test, production). Development is the default mongo 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: trello_effort_tracker_dev
      hosts:
        - localhost:27017
test:
  sessions:
    default:
      database: trello_effort_tracker_test
      hosts:
        - localhost:27017
production:
  autocreate_indexes: true
  persist_in_safe_mode: true

  sessions:
    default:
      database: trello_effort_tracker_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 = 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

rake console

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

rake "console[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 trello_effort_tracker_production --collection tracked_cards --out trello_effort_tracker_production.json

To reimport that db:

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

Google Docs exporter

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

rake "export:google_docs[my_sheet, tracking, 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

rake 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-p194@spikes"
PROJECT_PATH="/Users/$USER/Documents/workspace/trello_effort_tracker"
LC_ALL=en_US.UTF-8

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

Roadmap and improvements

We develop Trello Effort Tracker using Trello itself.

Contributing

To get started, sign the Contributor License Agreement.

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

https://github.com/xpepper/trello_effort_tracker

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