Torque

Introduction

Torque is a command line utility packaged as a Ruby gem. It compiles online data from a Pivotal Tracker project into a set of release notes for that project.

At start, Torque requests a Pivotal Tracker API token, which gives Torque access to information from your Pivotal Tracker projects. Torque then asks the user to choose one of their projects to begin to generate notes from.

Once configured, Torque requests data on the accepted stories from the current Pivotal project. It then compiles these stories into a first-draft release notes document. Depending on how consistently your team uses Pivotal Tracker, this document will contain:

  • A record of each feature that was added to the project since the last time Torque was run
  • A description of the feature
  • The date that this feature was accepted
  • A link to the Pivotal Tracker story that tracks this feature

Torque's default behavior is to document all the stories that were accepted since the last time Torque was run. For instance, if Torque was run on June 1st and then on June 10th, it would generate release notes from the stories that were accepted between June 1st and June 10th (inclusive). This is designed to make it easy to generate release notes each time new features are pushed to production: If Torque is run at the time of each new release, then it will generate notes for all the features that were added since the previous release. If needed, Torque can also generate notes for a custom date range.

Torque was designed and tested in a Ruby 2.0 environment.

Current Features

  • Automatically compiles all Pivotal Tracker stories accepted between the current date and the last time Torque was run
  • Compile stories accepted within a custom date range
  • Stores a record of each document as it's generated
  • Configuration script that automatically sets up a directory to use Torque
  • Project script that automatically displays/switches between your Pivotal Tracker projects
  • Ability to email the finished release notes from a personal email account to a pre-specified mailing list. (Currently can only send from accounts hosted by Gmail)

Note on Confidentiality

During usage, Torque will request some confidential information -- namely, your Pivotal Tracker API token and your email username/password. This information is stored in a local config file on your computer and is only used to access (respectively) Pivotal Tracker and your email server. It is never collected, sent to a 3rd party, or used for any other purpose.

Torque stores this data in a file called '.torqueinfo.yaml': Do not commit this file to your version control system!

Installation

# gem install torque

Configuration

To configure Torque, run in your project's root directory

# torque config

The configuration script will request a Pivotal Tracker API token, which can be found at https://www.pivotaltracker.com/profile#api. The token can be reset at any time by running:

# 'torque config -t/--token'

To change the output directory Torque writes its release notes to:

# 'torque config -o/--output [directory]'

To overwrite the Torque settings and/or output directory:

# 'torque config -f/--force'

Usage

In a directory that has been configured, run

# torque

Alternately, run Torque from a different directory by using the --root option:

# torque --root [configured/torque/directory]

This will compile release notes for all stories accepted since the last time you ran Torque in this directory.

To compile release notes for stories within a custom date range:

# torque -f [from] -t [to]

If [from] is set, [to] will default to today. If [to] is set, [from] will default to 1/1/1900.

To email the release notes from a personal email to Torque's mailing list:

# torque --email

Running with the 'verbose' option will print a running list of stories as they are added. Running with the 'silent' option will silence all output.

To display all available Pivotal Tracker projects or change your current project:

# torque project

To set up automatic emailing when the notes and add/remove from the mailing list:

# torque email

License

Copyright (c) 2013 Scrimmage

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.