trello_effort_tracker 0.0.3

data/.gitignore

@@ -0,0 +1,25 @@
+.DS_Store
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.tmtags
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+
+config.yml
+config.yml.piero
+mongoid.yml
+.rvmrc

data/.rspec

@@ -0,0 +1,3 @@
+--colour
+--format doc
+--order rand

data/.rvmrc.template

@@ -0,0 +1,2 @@
+rvm 1.9.3-p194@spikes --create
+rvm wrapper 1.9.3-p194@spikes textmate

data/.travis.yml

@@ -0,0 +1,21 @@
+language: ruby
+rvm:
+  - 1.9.3
+
+env:
+  global:
+    - developer_public_key: e/zPNGKOwapoxFWZs/CBTAhaoqrDTkqqz+InOmCUvGBcZBpUxH398nPLv8Hi\nNQSvWuspzqanyNbbQrTA/2XhsWF1gIFX+gNexYM7S+MxtRwUD3cpVT8DzVOS\nMuckdMTEAADVsm92vIX/bUs5igxD4+zfXlhzXUNDrzRlZnsUF2M=
+    - access_token_key: GG1Q8oq7GkaXjP0lbMgvQLLEi+LXOZlwmELqjPk39Exfy8114QUs2ki8nr9n\ndGO+tgOSZsCd/bt9IHxS3WWWU0INSYOTgp/prfsDDgosg7/Elk/b6w1OW0At\nX3VAjMeI0yAGloT6XB58LCFyrj6S2b4vCQqyaHR3tlTHai/5bMQ=
+    - developer_secret: jnWqZy2L5styLBGfgpZm9Unqog4KBlPTdtSHdFKG4I8PotrJEi6Kt2rSGljX\n8zFiRcnzelZSEEzGxa9z6pSMFuVz5Dkr3EK/Oa4+MpueMOXOoQA3zmty/865\n5Wokr1cEeJJOP/KXmnLgAkvPh9vOn7KEd8IlphsOkv5w+Rlmgb4=
+    - tracker_username=trackinguser
+    - MONGOID_ENV=test
+
+services:
+  - mongodb
+
+script: ./script/ci/run_build.sh
+
+before_script:
+  - mongo trello_effort_tracker_test --eval 'db.addUser("travis", "test");'
+  - "./script/ci/before_script.sh"
+

data/Gemfile

@@ -0,0 +1,22 @@
+source :rubygems
+
+gem 'trello_effort_tracker', :path => '.'
+
+gem 'ruby-trello', :require => 'trello'
+gem 'debugger'
+gem 'rainbow'
+gem 'chronic'
+
+gem 'mongoid'
+gem 'bson_ext'
+
+# google docs exporter
+gem 'google_drive'
+gem 'highline'
+
+group :test do
+  gem 'rake'
+  gem 'rspec'
+  gem 'rspec-mocks'
+  gem 'mongoid-rspec'
+end

data/Gemfile.lock

@@ -0,0 +1,101 @@
+PATH
+  remote: .
+  specs:
+    trello_effort_tracker (0.0.2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.2.11)
+      activesupport (= 3.2.11)
+      builder (~> 3.0.0)
+    activesupport (3.2.11)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    addressable (2.3.2)
+    bson (1.8.1)
+    bson_ext (1.8.1)
+      bson (~> 1.8.1)
+    builder (3.0.4)
+    chronic (0.9.0)
+    columnize (0.3.6)
+    debugger (1.2.3)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.1.1)
+      debugger-ruby_core_source (~> 1.1.5)
+    debugger-linecache (1.1.2)
+      debugger-ruby_core_source (>= 1.1.1)
+    debugger-ruby_core_source (1.1.6)
+    diff-lcs (1.1.3)
+    faraday (0.8.4)
+      multipart-post (~> 1.1)
+    google_drive (0.3.2)
+      nokogiri (>= 1.4.4, != 1.5.2, != 1.5.1)
+      oauth (>= 0.3.6)
+      oauth2 (>= 0.5.0)
+    highline (1.6.15)
+    httpauth (0.2.0)
+    i18n (0.6.1)
+    json (1.7.6)
+    jwt (0.1.5)
+      multi_json (>= 1.0)
+    mime-types (1.19)
+    mongoid (3.0.17)
+      activemodel (~> 3.1)
+      moped (~> 1.2)
+      origin (~> 1.0)
+      tzinfo (~> 0.3.22)
+    mongoid-rspec (1.5.6)
+      mongoid (>= 3.0.1)
+      rake
+      rspec (>= 2.9)
+    moped (1.3.2)
+    multi_json (1.5.0)
+    multipart-post (1.1.5)
+    nokogiri (1.5.6)
+    oauth (0.4.7)
+    oauth2 (0.8.0)
+      faraday (~> 0.8)
+      httpauth (~> 0.1)
+      jwt (~> 0.1.4)
+      multi_json (~> 1.0)
+      rack (~> 1.2)
+    origin (1.0.11)
+    rack (1.4.4)
+    rainbow (1.1.4)
+    rake (10.0.3)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.1)
+    ruby-trello (0.4.4.3)
+      activemodel
+      addressable (~> 2.3)
+      json
+      oauth (~> 0.4.5)
+      rest-client (~> 1.6.7)
+    tzinfo (0.3.35)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bson_ext
+  chronic
+  debugger
+  google_drive
+  highline
+  mongoid
+  mongoid-rspec
+  rainbow
+  rake
+  rspec
+  rspec-mocks
+  ruby-trello
+  trello_effort_tracker!

data/LICENSE.txt

@@ -0,0 +1,15 @@
+Pietro Di Bello
+2012
+
+In the original BSD license, both occurrences of the phrase "COPYRIGHT HOLDERS AND CONTRIBUTORS" in the disclaimer read "REGENTS AND CONTRIBUTORS".
+
+Here is the license template:
+
+Copyright (c) 2012, Pietro Di Bello
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,159 @@
+[![Build Status](https://secure.travis-ci.org/xpepper/trello_effort_tracker.png)](http://travis-ci.org/xpepper/trello_effort_tracker)
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/xpepper/trello_effort_tracker)
+
+# TrelloEffortTracker
+
+The purpose of this tool is to extract and track estimates and actual efforts on Trello cards.
+You just have to notify all of your estimates and efforts tracked on your Trello cards using a conventional format.
+This tool will extract and store these estimates and actual efforts to let you extract useful key metrics (e.g. estimate errors, remaining efforts, pair programming frequencies, and so on).
+
+The Trello API is used in readonly mode in this code, so all you need to access is your developer key.
+TrelloEffortTracker uses the [Trello API Ruby wrapper](https://github.com/jeremytregunna/ruby-trello) for this purpose.
+
+## Requirements
+* [rvm](https://rvm.io/rvm/install/)
+* [mongoDB](http://www.mongodb.org/) - mac users with homebrew will just run 'brew install mongodb' to have mongoDB installed on their machine.
+
+## Setup
+Copy the config template
+
+    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](http://mongoid.org/en/mongoid/docs/installation.html#configuration) to have more details).
+
+Then run bundle to get all the required gems:
+
+    bundle install
+
+### Where do I get an API key and API secret?
+Log in as a Trello user and visit [this URL](https://trello.com/1/appKey/generate) to get your developer\_public\_key and the developer\_public\_key.
+
+### Where do I get an API Access Token Key?
+You will need an access token to use ruby-trello, which trello tracker depends on. To get it, you'll need to 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 be told to give some key to the app, this is what you want to put in the access\_token\_key yml prop file.
+
+## 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.
+
+    tracker = TrelloTracker.new
+    tracker.track
+
+You can set the Trello's auth params in three ways
+
+* setting the three auth params via environment variables (ENV object)
+* using the config.yml (which remains the default mode)
+* passing into the constructor a hash containing the auth values, e.g.
+
+        tracker = TrelloTracker.new(
+         "developer_public_key" => "487635b55e6fe9021902fa763b4d101a",
+         "access_token_key" => "33bed56f2a12a49c9ba1c2d6ad3e2002e11a34358c3f3fe260d7fba746a06203",
+         "developer_secret" => "ab999c4396493dba4c04ade055eabfdfabdffd0ffd7c281a23234350a993524d")
+
+        tracker.track
+
+### 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
+
+
+### Storage configuration
+Tracking data collected from Trello are stored in a MongoDB, as configured in config/mongoid.yml.
+To define which mongodb env is actually used, just set the MONGOID_ENV env variable. Development is the default mongo environment.
+
+### 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)
+
+## 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.
+
+
+## Roadmap and improvements
+We develop Trello Effort Tracker using [Trello itself](https://trello.com/board/trello-effort-tracker-roadmap/509c3228dcb1ac3f1c018791).
+
+## Contributing
+
+Several ways you can contribute. Documentation, code, tests, feature requests, bug reports.
+
+Pull requests are welcome :)
+
+[@pierodibello](http://twitter.com/pierodibello)

data/Rakefile

@@ -0,0 +1,72 @@
+require 'trello_effort_tracker'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+task :specs   => :spec
+task :c       => :console
+
+desc "Open an irb session preloaded with this library, e.g. rake 'console[production]' will open a irb session with the production db env"
+task :console, [:db_env] do |t, args|
+  args.with_defaults(db_env: "development")
+  sh "export MONGOID_ENV=#{args.db_env}; irb -rubygems -I lib -r trello_effort_tracker.rb -r startup_trello.rb"
+end
+
+namespace :spec do
+  desc "Run fast specs"
+  RSpec::Core::RakeTask.new(:fast) do |t|
+    t.rspec_opts = '--tag ~needs_valid_configuration'
+  end
+
+  desc "Run slow specs"
+  RSpec::Core::RakeTask.new(:slow) do |t|
+    t.rspec_opts = '--tag needs_valid_configuration'
+  end
+end
+
+namespace :run do
+  include TrelloConfiguration
+
+  desc "Run on the cards tracked starting from a given day, e.g. rake 'run:from_day[2012-11-1]'"
+  task :from_day, [:starting_date, :db_env] => [:ensure_environment] do |t, args|
+    args.with_defaults(starting_date: Date.today.to_s, db_env: "development")
+    TrelloConfiguration::Database.load_env(args.db_env)
+
+    tracker = TrelloTracker.new
+    tracker.track(Date.parse(args.starting_date))
+  end
+
+  desc "Run on the cards tracked today, #{Date.today}"
+  task :today, [:db_env] => [:ensure_environment] do |t, args|
+    args.with_defaults(db_env: "development")
+    Rake.application.invoke_task("run:from_day[#{Date.today.to_s}, #{args.db_env}]")
+  end
+end
+
+namespace :export do
+  desc "Export all cards to a google docs spreadsheet, e.g. rake \"export:google_docs[my_sheet,tracking,production]\""
+  task :google_docs, [:spreadsheet, :worksheet, :db_env] => [:ensure_environment] do |t, args|
+    args.with_defaults(db_env: "development")
+    TrelloConfiguration::Database.load_env(args.db_env)
+
+    exporter = GoogleDocsExporter.new(args.spreadsheet, args.worksheet)
+    spreadsheet_url = exporter.export
+
+    puts "[DONE]".color(:green)
+    puts "Go to #{spreadsheet_url}"
+  end
+end
+
+task :ensure_environment do
+  %w{developer_public_key developer_secret access_token_key}.each do |each_name|
+    unless ENV[each_name] || authorization_params_from_config_file[each_name]
+      puts "ERROR: Missing <#{each_name}> environment variable."
+      exit 1
+    end
+  end
+  unless tracker_username
+    puts "ERROR: Missing <tracker_username> environment variable."
+    exit 1
+  end
+end

data/config/config.template.yml

@@ -0,0 +1,7 @@
+trello:
+  developer_public_key: <here put the key taken from https://trello.com/1/appKey/generate>
+  access_token_key: <here put the token taken in the 'Reading Private Data' section from https://trello.com/1/appKey/generate>
+  developer_secret: <here put the Secret (for OAuth signing) taken from https://trello.com/1/appKey/generate>
+
+tracker_username: <here put the Trello member used as recipient of the tracking notifications>
+google_docs_username: <here put your Google Docs username>

data/config/mongoid.template.yml

@@ -0,0 +1,24 @@
+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

data/lib/patches/trello/member.rb

@@ -0,0 +1,20 @@
+module Trello
+
+  class Member
+    def notifications_from(from_date)
+      notifications(limit:1000).select(&greater_than_or_equal_to(from_date)).select(&tracking_notification?)
+    end
+    
+    private
+
+    def greater_than_or_equal_to(from_date)
+      lambda { |notification| Chronic.parse(notification.date) >= from_date }
+    end
+
+    def tracking_notification?
+      lambda { |notification| notification.type == "mentionedOnCard" }
+    end
+    
+  end
+
+end

data/lib/startup_trello.rb

@@ -0,0 +1,2 @@
+include TrelloAuthorize
+authorize_on_trello

data/lib/trello_effort_tracker/effort.rb

@@ -0,0 +1,27 @@
+class Effort
+  include Mongoid::Document
+  include Mongoid::Timestamps
+
+  field :amount,  type: BigDecimal
+  field :date,    type: Date
+  field :tracking_notification_id
+
+  embeds_many :members
+  embedded_in :tracked_card
+
+  default_scope asc(:date)
+
+  validates_presence_of :amount, :date, :members
+
+  def ==(other)
+    return true if other.equal?(self)
+    return false unless other.kind_of?(self.class)
+
+    amount == other.amount && date == other.date && Set.new(members) == Set.new(other.members)
+  end
+
+  def to_s
+    "[#{date}] spent #{amount} hours by #{members.map(&:at_username).join(", ")}"
+  end
+
+end

data/lib/trello_effort_tracker/estimate.rb

@@ -0,0 +1,25 @@
+class Estimate
+  include Mongoid::Document
+  include Mongoid::Timestamps
+
+  field :amount,  type: BigDecimal
+  field :date,    type: Date
+  field :tracking_notification_id
+
+  embedded_in :tracked_card
+
+  default_scope asc(:date)
+
+  validates_presence_of :amount, :date
+
+  def ==(other)
+    return true if other.equal?(self)
+    return false unless other.kind_of?(self.class)
+
+    amount == other.amount && date == other.date
+  end
+
+  def to_s
+    "[#{date}] estimated #{amount} hours"
+  end
+end

data/lib/trello_effort_tracker/google_docs_exporter.rb

@@ -0,0 +1,67 @@
+require "google_drive"
+require 'highline/import'
+
+class GoogleDocsExporter
+  include TrelloConfiguration
+
+  def initialize(spreadsheet_name, worksheet_name)
+    @spreadsheet_name = spreadsheet_name || "trello effort tracking"
+    @worksheet_name   = worksheet_name || "tracking"
+  end
+
+  def export
+    Trello.logger.info "Running exporter from db env '#{db_environment}' to google docs '#{@spreadsheet_name.color(:green)}##{@worksheet_name.color(:green)}'..."
+
+    spreadsheet = google_docs_session.spreadsheet_by_title(@spreadsheet_name) || google_docs_session.create_spreadsheet(@spreadsheet_name)
+    worksheet = spreadsheet.worksheet_by_title(@worksheet_name) || spreadsheet.add_worksheet(@worksheet_name)
+
+    create_header(worksheet)
+    index = 2 # skip the header
+
+    cards = TrackedCard.all.reject(&:no_tracking?).sort_by(&:first_activity_date).reverse
+    cards.each do |card|
+      print ".".color(:green)
+      worksheet[index, columns[:user_story_id]] = card.short_id
+      worksheet[index, columns[:user_story_name]] = card.name
+      worksheet[index, columns[:start_date]] = card.working_start_date
+      worksheet[index, columns[:total_effort]] = card.total_effort
+      worksheet[index, columns[:last_estimate_error]] = card.last_estimate_error
+      card.estimates.each_with_index do |estimate, i|
+        worksheet[index, columns[:estimate]+i] = estimate.amount
+      end
+      index += 1
+    end
+
+    saved = worksheet.save
+    spreadsheet.human_url if saved
+  end
+
+  private
+
+  def google_docs_session(email=configuration["google_docs_username"])
+    @session ||= login(email)
+  end
+
+  def login(email)
+    username = ask("Enter your google docs username: ") { |q| q.default = email }
+    password = ask("Enter your google docs password: ") { |q| q.echo = false }
+
+    GoogleDrive.login(username, password)
+  end
+
+  def columns
+    @columns ||= {
+      user_story_id:        1,
+      user_story_name:      2,
+      start_date:           3,
+      total_effort:         4,
+      last_estimate_error:  5,
+      estimate:             6,
+    }
+  end
+
+  def create_header(worksheet)
+    worksheet.update_cells(1,1, [["ID", "Story Name", "Start Date", "Total Effort (hours)", "Last estimate error (%)", "First Estimate", "2nd estimate", "3rd estimate"]])
+  end
+
+end

data/lib/trello_effort_tracker/member.rb

@@ -0,0 +1,46 @@
+class Member
+  include Mongoid::Document
+  include Mongoid::Timestamps
+
+  field :trello_id
+  field :username
+  field :full_name
+  field :avatar_id
+  field :bio
+  field :url
+
+  embedded_in :effort
+
+  validates_presence_of :username
+
+  def self.build_from(trello_member)
+    trello_member_id = trello_member.id
+    trello_member.attributes.delete(:id)
+    new(trello_member.attributes.merge(trello_id: trello_member_id))
+  end
+
+  def at_username
+    "@#{username}"
+  end
+
+  def avatar_url
+    "https://trello-avatars.s3.amazonaws.com/#{avatar_id}/30.png"
+  end
+
+  def ==(other)
+    return true if other.equal?(self)
+    return false unless other.kind_of?(self.class)
+
+    username == other.username
+  end
+
+  def eql?(other)
+    return false unless other.instance_of?(self.class)
+    username == other.username
+  end
+
+  def hash
+    username.hash
+  end
+
+end

data/lib/trello_effort_tracker/mongoid_helper.rb

@@ -0,0 +1,13 @@
+module MongoidHelper
+  
+  def without_mongo_raising_errors(&block)
+    original_value = Mongoid.raise_not_found_error
+    Mongoid.raise_not_found_error = false
+    begin
+      block.call if block
+    ensure
+      Mongoid.raise_not_found_error = original_value
+    end
+  end
+  
+end