westarete-tracker-tools 0.3.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1,2 @@
+--format nested
+--color

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.8.7@westarete-tracker-tools

data/Gemfile

@@ -0,0 +1,30 @@
+source :rubygems
+
+# Tools for creating a gem
+gem 'jeweler', '1.5.2'
+
+# API wrapper for Pivotal Tracker
+gem 'pivotal-tracker', '0.3.0'
+
+# Validations and relationships
+gem 'activemodel', '3.0.3'
+
+group :development do
+  # Test framework
+  gem 'rspec', '2.2.0'
+
+  # Produce rspec output in junit format for jenkins
+  gem 'ci_reporter', '1.6.4'
+
+  # Measure test coverage
+  gem 'rcov', '0.9.9'
+  
+  # Automatically run tests as you code
+  gem 'autotest', '4.4.6'
+
+  # Record and play back API requests during tests
+  gem 'vcr', '1.4.0'
+
+  # Mock out API requests
+  gem 'fakeweb', '1.3.0'
+end

data/Gemfile.lock

@@ -0,0 +1,59 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ZenTest (4.4.2)
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activesupport (3.0.3)
+    autotest (4.4.6)
+      ZenTest (>= 4.4.1)
+    builder (2.1.2)
+    ci_reporter (1.6.4)
+      builder (>= 2.1.2)
+    diff-lcs (1.1.2)
+    fakeweb (1.3.0)
+    git (1.2.5)
+    happymapper (0.3.2)
+      libxml-ruby (~> 1.1.3)
+    i18n (0.5.0)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    libxml-ruby (1.1.4)
+    mime-types (1.16)
+    nokogiri (1.4.3.1)
+    pivotal-tracker (0.3.0)
+      builder
+      happymapper (>= 0.3.2)
+      nokogiri (~> 1.4.3.1)
+      rest-client (~> 1.6.0)
+    rake (0.8.7)
+    rcov (0.9.9)
+    rest-client (1.6.1)
+      mime-types (>= 1.16)
+    rspec (2.2.0)
+      rspec-core (~> 2.2)
+      rspec-expectations (~> 2.2)
+      rspec-mocks (~> 2.2)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
+    vcr (1.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activemodel (= 3.0.3)
+  autotest (= 4.4.6)
+  ci_reporter (= 1.6.4)
+  fakeweb (= 1.3.0)
+  jeweler (= 1.5.2)
+  pivotal-tracker (= 0.3.0)
+  rcov (= 0.9.9)
+  rspec (= 2.2.0)
+  vcr (= 1.4.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 West Arete Computing, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,190 @@
+# westarete-tracker-tools
+
+This gem contains a set of tools and extensions that West Arete uses to report
+on [Pivotal Tracker](https://www.pivotaltracker.com/) across all of its
+projects.
+
+## Goals
+
+* Extract the set of stories that are available to work on across all active 
+projects
+* Validate stories in the backlog to ensure that they meet our standards
+* Report on completed iterations for billing and reporting purposes
+* Wedge the following additional information into each feature:
+    * Risk
+    * Price
+
+## Manifesto
+
+This is an opinionated gem. It assumes that you are using Tracker the way that
+West Arete is using it. That is to say:
+
+* Stories are not available to be worked on until they are in the backlog
+* Features are not allowed into the backlog until they have all of the 
+following attributes:
+    * A substantial description
+    * A point estimate
+    * A risk rating (see below)
+    * A price or cost estimate (see below)
+* Stories should be requested by the project's stakeholder
+* Acceptance of a story implies that it is ready to be invoiced
+
+If these rules do not hold true for your organization, you may need to fork
+this project and modify the behavior so that it better suits your needs.
+
+### Risk
+
+West Arete assigns an objective risk rating to each feature. This helps us to
+achieve a balanced risk profile for each iteration for the sake of developer
+productivity and happiness. It also gives valuable feedback to the managers
+about how the feature should be priced, so that risk is apportioned fairly
+between West Arete and the client.
+
+Our ratings borrow from the rock climbing tradition of using movie ratings
+to communicate risk. A climb that is rated PG is generally less dangerous than
+one that is rated R. In the same way, we assign a risk rating to each feature:
+
+* G: I have implemented something exactly like this recently.
+* PG: I have implemented something quite similar to this.
+* PG-13: I know how to do this, but it will involve a gem, library, or 
+technique that I haven't used before.
+* R: I know how to do this, but I don't know exactly how long it will take; or
+it involves an entirely new environment; or it involves adopting outsiders' 
+code.
+* X: I'm not completely sure I will succeed at implementing this.
+
+Risk ratings are only assigned to features. They are not assigned to bugs,
+chores, or releases (although an average rating could probably be determined
+for the latter).
+
+There are a couple implicit ramifications of this system: 
+
+* Risk is dependent upon the person or team who will be implementing the
+  feature -- what is G for one person or team may be R for another.
+* Risk is dependent upon the implementation. The decision to implement a 
+feature using a new gem will increase the risk to at least PG-13, even if it's
+anticipated that it will be easier to accomplish (which may reduce the point
+estimate).
+
+Risk is encoded into a story in Tracker by enclosing it in square braces at
+the beginning of the feature's title. For example:
+
+    [PG-13] Geolocation
+
+### Price
+
+West Arete generally prices its services per feature. Whenever possible, the
+price is set as a fixed bid per story. However, when the risk for a feature is
+too high, the feature is usually implemented at an hourly rate so that the 
+risk is shared by both West Arete and the Client.
+
+With this library, prices are set in Tracker by having a manager comment on
+the story with the estimated price. The library picks up on this by searching
+the managers' comments for the words "cost" or "price" followed by a dollar
+figure. The most recent managers' comment that sets a price wins.
+
+## Setup
+
+You'll need to create a `.pivotal_tracker_api_token` file in your home
+directory. It should contain nothing but your API key from the bottom of [your
+Tracker profile page](https://www.pivotaltracker.com/profile).
+
+## Library
+
+This gem provides a clean, high-level reporting interface to the [Pivotal
+Tracker v3 API](https://www.pivotaltracker.com/help/api).
+
+Under the covers, this gem uses the [pivotal-tracker
+gem](https://github.com/jsmestad/pivotal-tracker) to do the actual
+communication with the Pivotal API. We've encapsulated that gem's object model
+to provide a higher level interface that adds our own custom functionality.
+
+However, our interface is not a superset of the pivotal-tracker gem -- we've
+only implemented the portions of the API that are useful to us.
+
+The API documentation for this gem is here:
+
+<http://rdoc.info/github/westarete/westarete-tracker-tools/master/frames>
+
+## Executables
+
+There are two command-line executables that are included with the gem. They 
+build upon the library to do some key reporting for us.
+
+Both scripts presume that they're being run on Mac OS X, so that they can 
+easily write to the clipboard.
+
+### backlog
+
+This script collects all stories that are available to be worked on across
+all projects. 
+
+Example usage:
+
+    bundle exec bin/backlog
+
+The standard output reports progress and any story validation errors that are
+encountered. A healthy backlog should have no errors. A link to each story
+is provided.
+
+After the script has completed successfully, a report of all the available
+stories is copied to the clipboard and is ready to be pasted into a
+spreadsheet.
+
+### done
+
+This script summarizes the accepted stories across all projects for a given 
+iteration. 
+
+It accepts a sole command line argument: an integer of zero or less, which
+represents the iteration offset. An offset of zero means the current
+iteration. An offset of -1 means the previous iteration. An offset of -2 means
+two iterations ago, etc. If the script is run with no arguments, it reports on
+the current iteration (an offset of 0).
+
+Example usage:
+
+    bundle exec bin/done -2
+
+This will gather all completed stories from two iterations ago. The standard
+output will report on progress and any invalid stories that are encountered.
+After completion, a summary of the stories will be left on the clipboard,
+ready to be pasted into a spreadsheet.
+
+### finished
+
+This script looks for stories that are close to being done. They may be in a
+state of "finished", "delivered", or "rejected". The team can run this
+periodically to see which stories or stakeholders need a nudge to get a story
+completed.
+
+### validate
+
+This script simply scrutinizes the backlog looking for stories that fail
+validation. It reports any problems and then exits with a non-zero status if
+any stories fail. It's designed to be run from a continuous integration
+system.
+
+## Contributing to westarete-tracker-tools
+ 
+* Check out the latest master to make sure the feature hasn't been implemented
+or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it 
+and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a 
+future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want 
+to have your own version, or is otherwise necessary, that is fine, but please 
+isolate to its own commit so I can cherry-pick around it.
+
+This project follows the conventions of [Semantic
+Versioning](http://semver.org/).
+
+## Copyright
+
+Copyright (c) 2011 West Arete Computing, Inc. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,79 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "westarete-tracker-tools"
+  gem.homepage = "http://github.com/westarete/westarete-tracker-tools"
+  gem.license = "MIT"
+  gem.summary = %Q{A set of tools and extensions that West Arete uses to report
+  on Pivotal Tracker.}
+  gem.description = %Q{
+This gem contains a set of tools and extensions that West Arete uses to report
+on Pivotal Tracker across all of its projects.
+
+Goals:
+
+* Extract the set of stories that are available to work on across all active 
+  projects
+* Validate stories in the backlog to ensure that they meet our standards
+* Report on completed iterations for billing and reporting purposes
+* Wedge the following additional information into each feature:
+    * Risk
+    * Price
+  }
+  gem.email = "scott@westarete.com"
+  gem.authors = ["Scott Woods"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+# Produce test output that jenkins can read.
+require 'ci/reporter/rake/rspec'     # use this if you're using RSpec
+# require 'ci/reporter/rake/cucumber'  # use this if you're using Cucumber
+# require 'ci/reporter/rake/test_unit' # use this if you're using Test::Unit
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new('spec')
+  RSpec::Core::RakeTask.new('spec:rcov') do |t|
+    t.rcov = true
+    t.rcov_opts = %w{ --exclude spec --exclude gems }
+  end
+  task :default => :spec
+rescue LoadError
+  puts "Could not find rspec gem. RSpec tasks will not be available."
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'spec'
+    test.pattern = 'spec/**/*_spec.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  puts "Could not find rcov gem. Coverage tasks will not be available."
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "westarete-tracker-tools #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/autotest/discover.rb

@@ -0,0 +1 @@
+Autotest.add_discovery { "rspec2" }

data/bin/backlog

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+
+# Extract all stories across all backlogs of all projects into a format
+# that's ready to be pasted into a spreadsheet. Also report on any validation
+# errors that are encountered.
+
+require 'rubygems'
+require 'bundler/setup'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'westarete-tracker-tools'
+
+include WestAreteTrackerTools
+
+number_of_problems = 0
+IO.popen('pbcopy', 'w') do |clipboard|
+  Project.all.each do |project|
+    puts "- #{project.name}"
+    project.backlog.each do |story|
+      if ! story.valid?
+        puts "  - Invalid Story"
+        puts "    story_type: #{story.story_type}"
+        puts "    name: \"#{story.name}\""
+        puts "    url: #{story.url}"
+        puts "    errors:"
+        story.errors.full_messages.each do |error|
+          puts "      - #{error}"
+        end
+        number_of_problems += 1
+      end
+      clipboard.puts [
+        nil,  # week starting
+        project.name, 
+        story.story_type, 
+        story.points,
+        story.risk,
+        nil,  # deliverable type
+        story.name,
+        nil,  # fixed / hourly
+        story.price,
+        story.url
+      ].join("\t")
+    end
+  end
+end
+puts "\nDone."
+puts "The master backlog has been copied to your clipboard and is ready to be pasted into a spreadsheet."
+exit number_of_problems