trello_effort_tracker 0.0.4 → 0.0.5

data/CHANGELOG

@@ -1,3 +1,7 @@
+0.0.5
+  - Improved docs
+  - Improved use of this tool as a gem
+
 0.0.4
   - A card moved into a DONE column is closed
 
@@ -12,6 +16,6 @@
   - Should be able to open a Trello console with a rake task
   - Avoid running the script if already run for that period
   - Tracking data is now persisted in a mongo database
-  
+
 0.0.1
   - Initial Release.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    trello_effort_tracker (0.0.3)
+    trello_effort_tracker (0.0.4)
       bson_ext
       chronic
       google_drive
@@ -47,8 +47,8 @@ GEM
     json (1.7.6)
     jwt (0.1.5)
       multi_json (>= 1.0)
-    mime-types (1.19)
-    mongoid (3.0.19)
+    mime-types (1.20.1)
+    mongoid (3.0.20)
       activemodel (~> 3.1)
       moped (~> 1.2)
       origin (~> 1.0)
@@ -82,7 +82,7 @@ GEM
     rspec-expectations (2.12.1)
       diff-lcs (~> 1.1.3)
     rspec-mocks (2.12.2)
-    ruby-trello (0.5.0)
+    ruby-trello (0.5.1)
       activemodel
       addressable (~> 2.3)
       json

data/README.md

@@ -6,40 +6,42 @@
 ## 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 extract useful key metrics (e.g. estimate errors, remaining efforts, pair programming frequencies, and so on).
+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](https://trello.com/card/time-tracking/4d5ea62fd76aa1136000000c/1054) on Trello's development board.
 
-We had the need to add time tracking to Trello, so we define 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 them in a simple domain model, backed on a persistent storage.
-Moreover, a web app will be soon available to properly present card estimates and efforts. We're working on it.
+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'. 
+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](#api_key).
 
-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](https://github.com/jeremytregunna/ruby-trello) for this purpose.
+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](https://github.com/jeremytregunna/ruby-trello) for this purpose.
 
-## Installation
+## Usage
+This tool can be used as a standalone gem or cloning this git repo.
 
-```
-# gem install trello_effort_tracker
+### Installation as a ruby gem
+
+```shell
+gem install trello_effort_tracker
 ```
 
-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](https://github.com/xpepper/trello_effort_tracker/issues).
+### Installation cloning the repo
 
-## Requirements
-* [mongoDB](http://www.mongodb.org/) - mac users with homebrew will just run 'brew install mongodb' to have mongoDB installed on their machine.
-* [rvm](https://rvm.io/rvm/install/) (optional)
+```shell
+git clone git://github.com/xpepper/trello_effort_tracker.git
+```
 
-## Setup
-Copy the config template
+Then cd in the lib and copy the config template
 
 ```shell
+cd trello_effort_tracker
 cp config/config.template.yaml config/config.yml
 ```
 
@@ -59,6 +61,15 @@ 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](https://github.com/xpepper/trello_effort_tracker/issues).
+
+## Requirements
+* [mongoDB](http://www.mongodb.org/) - macosx users with homebrew will just run 'brew install mongodb' to have mongoDB installed on their machine.
+* (optional) [rvm](https://rvm.io/rvm/install/) is useful (but optional) for development
+
+
+
 ### <a id="api_key"></a>Where do I get an API key?
 Log in to Trello with your account and visit [https://trello.com/1/appKey/generate](https://trello.com/1/appKey/generate) to get your developer\_public\_key.
 
@@ -75,7 +86,7 @@ The best way is to use one of the rake task defined, e.g.
 ```ruby
 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: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
 ```
@@ -83,22 +94,70 @@ rake 'run:from_day[2012-11-1, production]'  # will extract tracked data starting
 Or you may just create a TrelloTracker instance and execute its track method.
 
 ```ruby
+require 'trello_effort_tracker'
+
 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)
-* passing into the constructor a hash containing the auth values, e.g.
-* using the config.yml (which remains the default mode)
+### 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:
+
+```yml
+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:
 
 ```ruby
 tracker = TrelloTracker.new(
- "developer_public_key" => "487635b55e6fe9021902fa763b4d101a",
- "access_token_key" => "33bed56f2a12a49c9ba1c2d6ad3e2002e11a34358c3f3fe260d7fba746a06203")
+ 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
 
@@ -106,9 +165,11 @@ You can open a irb console with the ruby-trello gem and this gem loaded, so that
 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.
+The default env is development. To load a console in the (e.g.) production db env, execute:
+
+```ruby
+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.
@@ -160,6 +221,8 @@ Sending a tracking notification with the word 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:
 
@@ -226,4 +289,4 @@ The best way to get your changes merged back into core is as follows:
 1. Push the branch up to GitHub
 1. Send a pull request for your branch
 
-[@pierodibello](http://twitter.com/pierodibello)
+[@pierodibello](http://twitter.com/pierodibello)

data/Rakefile

@@ -5,7 +5,6 @@ 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|
@@ -13,6 +12,10 @@ task :console, [:db_env] do |t, args|
   sh "export MONGOID_ENV=#{args.db_env}; irb -rubygems -I lib -r trello_effort_tracker.rb -r startup_trello.rb"
 end
 
+task :c, [:db_env] do |t, args|
+  Rake::Task[:console].invoke(args.db_env)
+end
+
 namespace :spec do
   desc "Run fast specs"
   RSpec::Core::RakeTask.new(:fast) do |t|

data/lib/trello_effort_tracker/tracked_card.rb

@@ -28,7 +28,8 @@ class TrackedCard
   def self.update_or_create_with(trello_card)
     tracked_card = find_or_create_by(trello_id: trello_card.id)
     trello_card.attributes.delete(:id)
-    updated_successfully = tracked_card.update_attributes(trello_card.attributes.merge(done: trello_card.in_done_column?))
+    tracked_card_attributes = trello_card.attributes.merge(done: trello_card.in_done_column?)
+    updated_successfully = tracked_card.update_attributes(tracked_card_attributes)
     return tracked_card if updated_successfully
   end
 

data/lib/trello_effort_tracker/trello_authorize.rb

@@ -4,12 +4,12 @@ module TrelloAuthorize
 
   def authorize_on_trello(auth_params={})
     %w{developer_public_key access_token_key}.each do |key|
-      auth_params[key] ||= ENV[key] || authorization_params_from_config_file[key]
+      auth_params[key.to_sym] ||= ENV[key] || authorization_params_from_config_file[key]
     end
 
     Trello.configure do |config|
-      config.developer_public_key = auth_params["developer_public_key"]
-      config.member_token         = auth_params["access_token_key"]
+      config.developer_public_key = auth_params[:developer_public_key]
+      config.member_token         = auth_params[:access_token_key]
     end
   end
 

data/lib/trello_effort_tracker/trello_configuration.rb

@@ -1,7 +1,7 @@
 module TrelloConfiguration
 
-  def tracker_username
-    @tracker_username ||= ENV["tracker_username"] || configuration["tracker_username"]
+  def tracker_username(forced_tracker_username=nil)
+    @tracker_username ||= forced_tracker_username || ENV["tracker_username"] || configuration["tracker_username"]
   end
 
   def authorization_params_from_config_file
@@ -9,9 +9,9 @@ module TrelloConfiguration
   end
 
   class Database
-    def self.load_env(db_env)
+    def self.load_env(db_env, mongoid_configuration_path=nil)
       ENV['MONGOID_ENV'] = db_env
-      Mongoid.load!("config/mongoid.yml", db_env)
+      Mongoid.load!(mongoid_configuration_path || "config/mongoid.yml", db_env)
       Trello.logger.info "Mongo db env: #{db_env.color(:green)}."
     end
   end

data/lib/trello_effort_tracker/trello_tracker.rb

@@ -4,8 +4,9 @@ class TrelloTracker
 
   trap("SIGINT") { exit! }
 
-  def initialize(custom_auth_params = {})
-    authorize_on_trello(custom_auth_params)
+  def initialize(custom_config_params = {})
+    authorize_on_trello(custom_config_params)
+    tracker_username(custom_config_params[:tracker_username])
   end
 
   def track(starting_date=Date.today)

data/lib/trello_effort_tracker/version.rb

@@ -1,3 +1,3 @@
 class TrelloEffortTracker
-  VERSION = '0.0.4'
+  VERSION = '0.0.5'
 end

data/lib/trello_effort_tracker.rb

@@ -4,6 +4,7 @@ require 'set'
 require 'yaml'
 require 'chronic'
 require 'mongoid'
+require 'forwardable'
 
 require 'trello_effort_tracker/mongoid_helper'
 require 'trello_effort_tracker/trello_configuration'
@@ -24,6 +25,6 @@ require 'trello_effort_tracker/google_docs_exporter'
 require 'patches/trello/member'
 require 'patches/trello/card'
 
-TrelloConfiguration::Database.load_env(ENV['MONGOID_ENV'] || "development")
+TrelloConfiguration::Database.load_env(ENV['MONGOID_ENV'] || "development", ENV['MONGOID_CONFIG_PATH'])
 
-Trello.logger.level = Logger::DEBUG
+Trello.logger.level = Logger::DEBUG

data/spec/integration/trello_tracker_spec.rb

@@ -13,14 +13,14 @@ describe TrelloTracker do
 
   let(:config) {
     # auth params for trackinguser_for_test/testinguser!
-    OpenStruct.new(tracker_username:  "trackinguser_for_test",
-                   developer_key:     "ef7c400e711057d7ba5e00be20139a33",
-                   access_token:      "9047d8fdbfdc960d41910673e300516cc8630dd4967e9b418fc27e410516362e")
+    OpenStruct.new(tracker:  "trackinguser_for_test",
+                   dev_key:  "ef7c400e711057d7ba5e00be20139a33",
+                   token:    "9047d8fdbfdc960d41910673e300516cc8630dd4967e9b418fc27e410516362e")
   }
 
   it "tracks some estimates and efforts", :needs_valid_configuration => true do
-    with_trackinguser(config.tracker_username) do
-      tracker = TrelloTracker.new("developer_public_key" => config.developer_key, "access_token_key" => config.access_token)
+    without_logging do
+      tracker = TrelloTracker.new(tracker_username: config.tracker, developer_public_key: config.dev_key, access_token_key: config.token)
       tracker.track(DateTime.parse("2013-01-28"))
     end
 
@@ -53,16 +53,13 @@ describe TrelloTracker do
 
   private
 
-  def with_trackinguser(tracking_user, &block)
-    original_tracker = ENV["tracker_username"]
+  def without_logging(&block)
     original_error_level = Trello.logger.level
 
     begin
-      ENV["tracker_username"] = tracking_user
       Trello.logger.level = Logger::WARN
       block.call unless block.nil?
     ensure
-      ENV["tracker_username"] = original_tracker
       Trello.logger.level = original_error_level
     end
   end

data/spec/trello_authorize_spec.rb

@@ -19,7 +19,7 @@ describe TrelloAuthorize do
       ENV["developer_public_key"] = ENV["access_token_key"] = "anything"
       YAML.should_receive(:load_file).never
 
-      authorize_on_trello("developer_public_key" => "custom_dpk", "access_token_key" => "custom_atk")
+      authorize_on_trello(developer_public_key: "custom_dpk", access_token_key: "custom_atk")
 
       Trello.client.auth_policy.developer_public_key.should == "custom_dpk"
       Trello.client.auth_policy.member_token.should         == "custom_atk"
@@ -31,7 +31,7 @@ describe TrelloAuthorize do
 
       YAML.should_receive(:load_file).never
 
-      authorize_on_trello("any" => "thing")
+      authorize_on_trello(any: "thing")
 
       Trello.client.auth_policy.developer_public_key.should == "my_dpk"
       Trello.client.auth_policy.member_token.should         == "my_atk"
@@ -43,7 +43,7 @@ describe TrelloAuthorize do
       config_hash = {"trello" => { "developer_public_key" => "any_dpk", "access_token_key" => "any_atk"}}
       YAML.should_receive(:load_file).with("config/config.yml").and_return(config_hash)
 
-      authorize_on_trello("any" => "thing")
+      authorize_on_trello(any: "thing")
 
       Trello.client.auth_policy.developer_public_key.should == "any_dpk"
       Trello.client.auth_policy.member_token.should         == "any_atk"

data/spec/trello_configuration_spec.rb

@@ -11,22 +11,22 @@ describe TrelloConfiguration do
 
       authorization_params_from_config_file["developer_public_key"].should == "any_dpk"
       authorization_params_from_config_file["access_token_key"].should == "any_atk"
-    end    
+    end
   end
-  
+
   describe "#tracker_username" do
     before(:each) do
       @original = ENV["tracker_username"]
     end
-    
+
     after(:each) do
       ENV["tracker_username"] = @original
     end
-    
+
     it "searches for the trello tracker username first from an env var" do
       ENV["tracker_username"] = "my_tracker"
       YAML.should_receive(:load_file).never
-    
+
       tracker_username.should == "my_tracker"
     end
 
@@ -34,10 +34,10 @@ describe TrelloConfiguration do
       ENV["tracker_username"] = nil
       config_hash = {"tracker_username" => "my_trello_tracker" }
       YAML.should_receive(:load_file).with("config/config.yml").and_return(config_hash)
-      
+
       tracker_username.should == "my_trello_tracker"
     end
-    
+
   end
 
 end

data/spec/trello_tracker_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+describe TrelloTracker do
+
+  before(:each) do
+    @original = ENV["tracker_username"]
+    ENV["tracker_username"] = "my_tracker"
+  end
+  
+  after(:each) do
+    ENV["tracker_username"] = @original
+  end
+  
+  it "force the trello tracker username in the constructor" do    
+    tracker = TrelloTracker.new(tracker_username: "any_other_tracker")
+
+    tracker.tracker_username.should == "any_other_tracker"
+  end
+
+  it "takes the tracker username from the ENV var tracker_username" do
+    tracker = TrelloTracker.new
+
+    tracker.tracker_username.should == "my_tracker"
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trello_effort_tracker
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-03 00:00:00.000000000 Z
+date: 2013-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-trello
@@ -182,6 +182,7 @@ files:
 - spec/tracking_factory_spec.rb
 - spec/trello_authorize_spec.rb
 - spec/trello_configuration_spec.rb
+- spec/trello_tracker_spec.rb
 - trello_effort_tracker.gemspec
 homepage: http://xplayer.wordpress.com
 licenses: []