tracco 0.0.14 → 0.0.15

data/CHANGELOG

@@ -1,3 +1,19 @@
+
+0.0.15 / 2013-03-01
+==================
+  * Introducing the Tracco namespace to avoid name collisions. All mongo collections will need to be copied from tracked_cards to tracco_tracked_cards
+
+  All existing collections will need to be renamed from tracked_cards to tracco_tracked cards.
+  > mongo trello_effort_tracker_dev
+  > db.tracked_cards.copyTo("tracco_tracked_cards");
+
+  * Update README.md
+  * Renaming the 'tracking event' into 'tracking notification'
+  * Renaming the 'tracking notification' into 'tracking event'
+  * Moving a spec in the proper folder
+  * Moving the models specs in a proper spec subfolder
+  * Moving all the models (tracked_cards, estimates, efforts and members) in a proper 'models' folder
+
 0.0.14 / 2013-02-27
 ==================
   * TrackedCard#contains_effort? is considering all the card's efforts, even the muted ones, so that a muted effort won't be re-added from Trello to Tracco

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    tracco (0.0.14)
+    tracco (0.0.15)
       bson_ext
       chronic
       google_drive

data/README.md

@@ -4,8 +4,8 @@
 # Tracco
 
 ## What is Tracco?
-Tracco is a Trello effort tracker: the purpose of Tracco is to extract and track estimates and actual efforts out of the cards on your Trello boards.
-You simply notify all of your estimates and efforts tracked on your Trello cards using a conventional format.
+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 notify all of your estimates and efforts tracked on your Trello cards using a simple conventional format.
 Tracco 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 Tracco?
@@ -96,7 +96,7 @@ Or you may just create a TrelloTracker instance and execute its track method.
 ```ruby
 require 'tracco'
 
-tracker = TrelloTracker.new
+tracker = Tracco::TrelloTracker.new
 tracker.track
 ```
 
@@ -148,7 +148,7 @@ Through the following environment variables (ENV object):
 Passing into the constructor a hash containing the auth values:
 
 ```ruby
-tracker = TrelloTracker.new(
+tracker = Tracco::TrelloTracker.new(
  developer_public_key: "487635b55e6fe9021902fa763b4d101a",
  access_token_key: "33bed56f2a12a49c9ba1c2d6ad3e2002e11a34358c3f3fe260d7fba746a06203",
  tracker_username: "my_personal_tracker")

data/lib/patches/trello/card.rb

@@ -1,7 +1,8 @@
+# Reopening the Trello::Card class to add some helper methods
 module Trello
-
   class Card
-    # Reopening the Trello::Card class to add a method detecting a card moved in a DONE column
+
+    # Tells whether a card is in a list with a name starting with "DONE"
     def in_done_column?
       list_name = ""
       begin

data/lib/patches/trello/member.rb

@@ -1,7 +1,9 @@
+# Reopening the Trello::Member class to add some helper methods
 module Trello
   class Member
-    # Reopening the Trello::Member class to add a notifications helper method
-    def notifications_since(starting_date)
+
+    # Fetch all the direct notifications sent to the 'tracking user' starting from a given date
+    def tracking_notifications_since(starting_date)
       notifications(limit:1000).select(&greater_than_or_equal_to(starting_date)).select(&tracking_notification?)
     end
 

data/lib/tasks/tasks.rake

@@ -16,7 +16,7 @@ namespace :run do
     args.with_defaults(starting_date: Date.today.to_s, db_env: "development")
     TrelloConfiguration::Database.load_env(args.db_env)
 
-    tracker = TrelloTracker.new
+    tracker = Tracco::TrelloTracker.new
     tracker.track(Date.parse(args.starting_date))
   end
 
@@ -33,7 +33,7 @@ namespace :export do
     args.with_defaults(db_env: "development")
     TrelloConfiguration::Database.load_env(args.db_env)
 
-    exporter = GoogleDocsExporter.new(args.spreadsheet, args.worksheet)
+    exporter = Tracco::GoogleDocsExporter.new(args.spreadsheet, args.worksheet)
     spreadsheet_url = exporter.export
 
     puts "[DONE]".color(:green)

data/lib/tracco/google_docs_exporter.rb

@@ -1,67 +1,70 @@
 require "google_drive"
 require 'highline/import'
 
-class GoogleDocsExporter
-  include TrelloConfiguration
+module Tracco
+  class GoogleDocsExporter
+    include TrelloConfiguration
 
-  def initialize(spreadsheet_name, worksheet_name)
-    @spreadsheet_name = spreadsheet_name || "trello effort tracking"
-    @worksheet_name   = worksheet_name || "tracking"
-  end
+    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)}'..."
+    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)
+      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
+      create_header(worksheet)
+      index = 2 # skip the header
 
-    cards = TrackedCard.all_tracked_cards(:method => :first_activity_date, :order => :desc)
-    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
+      cards = TrackedCard.all_tracked_cards(:method => :first_activity_date, :order => :desc)
+      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
-      index += 1
+
+      saved = worksheet.save
+      spreadsheet.human_url if saved
     end
 
-    saved = worksheet.save
-    spreadsheet.human_url if saved
-  end
+    private
 
-  private
+    def google_docs_session(email=configuration["google_docs_username"])
+      @session ||= login(email)
+    end
 
-  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 }
 
-  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
 
-    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 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
 
-  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/tracco/models/effort.rb

@@ -0,0 +1,40 @@
+module Tracco
+  class Effort
+    include Mongoid::Document
+    include Mongoid::Timestamps
+    include Mongoid::MultiParameterAttributes
+
+    field :amount,  type: BigDecimal
+    field :date,    type: Date
+    field :tracking_notification_id
+    field :muted,   type: Boolean, default: false
+
+    embeds_many :members
+    embedded_in :tracked_card
+
+    default_scope where(muted: false).asc(:date)
+
+    validates_presence_of :amount, :date, :members
+
+    def amount_per_member
+      amount / members.size
+    end
+
+    def include?(member)
+      members.include?(member)
+    end
+
+    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
+
+end

data/lib/tracco/models/estimate.rb

@@ -0,0 +1,29 @@
+module Tracco
+  class Estimate
+    include Mongoid::Document
+    include Mongoid::Timestamps
+    include Mongoid::MultiParameterAttributes
+
+    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
+
+end

data/lib/tracco/models/member.rb

@@ -0,0 +1,64 @@
+module Tracco
+  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
+      trello_member.avatar_url(size: :small)
+    end
+
+    def effort_spent(from_date=nil)
+      cards = TrackedCard.with_effort_spent_by(username)
+      efforts = cards.map(&:efforts).compact.flatten
+      efforts = efforts.select {|e| e.date >= from_date} if from_date
+      efforts.select { |effort| effort.include?(self) }.inject(0) { |total, effort| total + effort.amount_per_member }
+    end
+    alias_method :effort_spent_since, :effort_spent
+
+    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
+
+    private
+
+    def trello_member
+      @trello_member ||= Trello::Member.new("id" => trello_id, "fullName" => full_name, "username" => username,
+                                            "avatarHash" => avatar_id, "bio" => bio, "url" => url)
+    end
+
+  end
+
+end

data/lib/tracco/models/tracked_card.rb

@@ -0,0 +1,148 @@
+module Tracco
+  class TrackedCard
+    include Mongoid::Document
+    include Mongoid::Timestamps
+    extend MongoidHelper
+
+    field :name
+    field :description
+    field :short_id,    type: Integer
+    field :trello_id
+    field :done,        type: Boolean
+    field :due,         type: Date
+    field :closed,      type: Boolean
+    field :url
+    field :pos
+
+    embeds_many :estimates
+    embeds_many :efforts
+
+    validates_presence_of :name, :short_id, :trello_id
+    validates_numericality_of :short_id
+
+    scope :with_effort_spent_by, ->(username){ where("efforts.members.username" => username) }
+
+    def self.find_by_trello_id(trello_id)
+      without_mongo_raising_errors do
+        find_by(trello_id: trello_id)
+      end
+    end
+
+    def self.update_or_create_with(trello_card)
+      tracked_card = find_or_create_by(trello_id: trello_card.id)
+      trello_card.attributes.delete(:id)
+      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
+
+    def self.all_tracked_cards(sorting_options = {})
+      cards = all.reject(&:no_tracking?)
+      cards.sort_by!(&sorting_options[:sort_by].to_sym) if sorting_options[:sort_by]
+      cards.reverse! if sorting_options[:order] == :desc
+      return cards
+    end
+
+    def self.build_from(trello_card)
+      trello_card_id = trello_card.id
+      trello_card.attributes.delete(:id)
+      new(trello_card.attributes.merge(trello_id: trello_card_id))
+    end
+
+    def self.efforts_between(search_options)
+      condition = {}
+      {'$gte' => :from_date, '$lte' => :to_date}.each do |selection, option_key|
+        condition[selection] = search_options[option_key] if search_options[option_key]
+      end
+
+      where("efforts.date" => condition)
+    end
+
+    def status
+      if done?
+        :done
+      elsif efforts.empty?
+        :todo
+      else
+        :in_progress
+      end
+    end
+
+    def add(tracking)
+      tracking.add_to(self)
+    end
+
+    def add!(tracking)
+      add(tracking) && save!
+    end
+
+    def contains_effort?(effort)
+      efforts.unscoped.any? { |e| e.tracking_notification_id == effort.tracking_notification_id }
+    end
+
+    def contains_estimate?(estimate)
+      estimates.any? { |e| e.tracking_notification_id == estimate.tracking_notification_id }
+    end
+
+    def no_tracking?
+      first_activity_date.nil?
+    end
+
+    def first_activity_date
+      [working_start_date, first_estimate_date].compact.min
+    end
+
+    def working_start_date
+      efforts.sort_by(&:date).first.date if efforts.present?
+    end
+
+    def first_estimate_date
+      estimates.sort_by(&:date).first.date if estimates.present?
+    end
+
+    def last_estimate_date
+      estimates.sort_by(&:date).last.date if estimates.present?
+    end
+
+    def total_effort
+      efforts.map(&:amount).inject(0, &:+)
+    end
+
+    def members
+      efforts.map(&:members).flatten.uniq
+    end
+
+    def last_estimate_error
+      estimate_errors.last
+    end
+
+    def estimate_errors
+      return [] if estimates.empty? || efforts.empty?
+
+      estimate_errors = []
+      estimates.each do |each|
+        estimate_errors << (100 * ((total_effort - each.amount) / each.amount * 1.0)).round(2)
+      end
+
+      estimate_errors
+    end
+
+    def trello_notifications
+      # TODO select all efforts, even the muted ones?
+      notification_ids = efforts.map(&:tracking_notification_id) | estimates.map(&:tracking_notification_id)
+      notification_ids.map { |id| Trello::Notification.find(id) rescue nil }.compact.sort_by(&:date)
+    end
+
+    def to_s
+      "[#{name}]. Total effort: #{total_effort}h. Estimates #{estimates.map(&:to_s)}. Efforts: #{efforts.map(&:to_s)}"
+    end
+
+    def ==(other)
+      return true if other.equal?(self)
+      return false unless other.kind_of?(self.class)
+      trello_id == other.trello_id
+    end
+
+  end
+
+end

data/lib/tracco/tracking/base.rb

@@ -1,82 +1,85 @@
-module Tracking
-  module Base
-    extend Forwardable
-    include TrelloConfiguration
-
-    TIME_CONVERTERS = {
-      'h' => lambda { |estimate| estimate },
-      'd' => lambda { |estimate| estimate * 8 },
-      'g' => lambda { |estimate| estimate * 8 },
-      'p' => lambda { |estimate| estimate / 2  }
-    }
-
-    DURATION_REGEXP = '(\d+\.?\d*[phdg])'
-    DATE_REGEXP = /(\d{2})\.(\d{2})\.(\d{4})/
-
-    # delegate to the trello notification the member_creator method aliased as 'notifier'
-    def_delegator :@tracking_notification, :member_creator, :notifier
-
-    def initialize(tracking_notification)
-      @tracking_notification = tracking_notification
-    end
-
-    def date
-      Chronic.parse(date_as_string).to_date
-    end
+module Tracco
+  module Tracking
+    module Base
+      extend Forwardable
+      include TrelloConfiguration
+
+      TIME_CONVERTERS = {
+        'h' => lambda { |estimate| estimate },
+        'd' => lambda { |estimate| estimate * 8 },
+        'g' => lambda { |estimate| estimate * 8 },
+        'p' => lambda { |estimate| estimate / 2  }
+      }
+
+      DURATION_REGEXP = '(\d+\.?\d*[phdg])'
+      DATE_REGEXP = /(\d{2})\.(\d{2})\.(\d{4})/
+
+      # delegate to the trello notification the member_creator method aliased as 'notifier'
+      def_delegator :@tracking_notification, :member_creator, :notifier
+
+      def initialize(tracking_notification)
+        @tracking_notification = tracking_notification
+      end
 
-    def to_s
-      "[#{date}] From #{notifier.username.color(:green)}\t on card '#{trello_card.name.color(:yellow)}': #{raw_text}"
-    end
+      def date
+        Chronic.parse(date_as_string).to_date
+      end
 
-    private
+      def to_s
+        "[#{date}] From #{notifier.username.color(:green)}\t on card '#{trello_card.name.color(:yellow)}': #{raw_text}"
+      end
 
-    def tracking_notification
-      @tracking_notification
-    end
+      private
 
-    def trello_card
-      @trello_card ||= tracking_notification.card
-    end
+      def tracking_notification
+        @tracking_notification
+      end
 
-    def notification_date
-      Chronic.parse(tracking_notification.date).to_date
-    end
+      def trello_card
+        @trello_card ||= tracking_notification.card
+      end
 
-    def raw_tracking
-      raw_text.gsub("@#{tracker_username}", "")
-    end
+      def notification_date
+        Chronic.parse(tracking_notification.date).to_date
+      end
 
-    def raw_text
-      tracking_notification.data['text']
-    end
+      def raw_tracking
+        raw_text.gsub("@#{tracker_username}", "")
+      end
 
-    def convert_to_hours(duration_as_string)
-      return if duration_as_string.nil?
+      def raw_text
+        tracking_notification.data['text']
+      end
 
-      time_scale = duration_as_string.slice!(-1)
-      converter = TIME_CONVERTERS[time_scale]
-      converter.call(Float(duration_as_string))
-    end
+      def convert_to_hours(duration_as_string)
+        return if duration_as_string.nil?
 
-    def date_as_string
-      case raw_tracking
-      when DATE_REGEXP
-        day, month, year = raw_tracking.scan(DATE_REGEXP).flatten
-        "#{year}-#{month}-#{day}"
-      when /yesterday\s+\+#{DURATION_REGEXP}/, /\+#{DURATION_REGEXP}\s+yesterday/
-          (notification_date - 1).to_s
-      else
-        tracking_notification.date
+        time_scale = duration_as_string.slice!(-1)
+        converter = TIME_CONVERTERS[time_scale]
+        converter.call(Float(duration_as_string))
       end
-    end
 
-    def extract_match_from_raw_tracking(regexp)
-      extracted = nil
-      raw_tracking.scan(regexp) do |match|
-        extracted = match.first
+      def date_as_string
+        case raw_tracking
+        when DATE_REGEXP
+          day, month, year = raw_tracking.scan(DATE_REGEXP).flatten
+          "#{year}-#{month}-#{day}"
+        when /yesterday\s+\+#{DURATION_REGEXP}/, /\+#{DURATION_REGEXP}\s+yesterday/
+            (notification_date - 1).to_s
+        else
+          tracking_notification.date
+        end
       end
 
-      extracted
+      def extract_match_from_raw_tracking(regexp)
+        extracted = nil
+        raw_tracking.scan(regexp) do |match|
+          extracted = match.first
+        end
+
+        extracted
+      end
     end
   end
+
 end

data/lib/tracco/tracking/card_done_tracking.rb

@@ -1,10 +1,13 @@
-module Tracking
-  class CardDoneTracking
-    include Base
+module Tracco
+  module Tracking
+    class CardDoneTracking
+      include Base
 
-    def add_to(card)
-      card.done = true
-    end
+      def add_to(card)
+        card.done = true
+      end
 
+    end
   end
+
 end