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
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 isconfig/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:
- Clone down your fork
- Create a thoughtfully named topic branch to contain your change
- Hack away
- Add tests and make sure everything still passes by running
rake spec
- If you are adding new functionality, document it in the README
- Do not change the version number, we will do that on our end
- If necessary, rebase your commits into logical chunks, without errors
- Push the branch up to GitHub
- Send a pull request for your branch