westarete-tracker-tools

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

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.

Library

This gem provides a clean, high-level reporting interface to the Pivotal Tracker v3 API.

Under the covers, this gem uses the pivotal-tracker gem 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.