Torque
Introduction
Torque is a command line utility that compiles data from your Pivotal Tracker project into a set of release notes for that project.
At start, Torque requests a Pivotal Tracker API token, providing it access to info from your Pivotal Tracker projects. It then requests a project for which to generate release notes.
After this one time configuration, Torque can begin generating notes. To do this, it requests data on accepted stories from your Pivotal project and 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 it 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 or for any number of past project iterations.
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
- Store a record of each document on generation
- Compile stories accepted within a custom date range
- Filtering stories by label, owner and/or story type
- Generate notes for specific number of completed project iterations
- Format the release notes according to a customizable formatting string
- Configuration script that automatically sets up a directory to use Torque
- Display all of your current Pivotal Tracker projects and easily switch between them
- 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 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 generate notes for X number of completed iterations of your project:
# torque --iterations X
To filter your results by story label, owner or type:
# torque --label list+of,labels
# torque --owner "list + of , owners"
# torque --type "list, of + story types"
When using filters:
- "," => OR
- "+" => AND
- "+" is evaluated before ","
For example, "ios + android, ios + web" becomes
("ios" AND "android") OR ("ios" AND "web")
The "owner" filter will try to match against first/middle/last names as well as full names. For instance, '--owner Lee' will match stories owned by (eg) "Lee Grant", "Jake Lee", or "John Lee Jones".
To email the release notes from a personal email to Torque's mailing list:
# torque --email
Running with '-v/--verbose' will print a running list of stories as they are added. Running with '-s/--silent' will silence all output.
To display all available Pivotal Tracker projects or change your current project:
# torque project
To set up automatic emailing of the notes and add/remove from the mailing list:
# torque email
To view/change the format of the notes that Torque generates:
# torque format
Formatting
By default, stories are formatted like this:
12345678
Story Name
Accepted on 2012/12/21
https://www.pivotaltracker.com/story/show/12345678
Short description of story goes here
- This is a side note
- This is another side note
To change the way that stories are formatted, use 'torque format -s/--set'. Alternately, use 'torque format -e/--example' to see some sample output from a new format.
The format is set by way of a "formatting string", a mix of plain text and parameters (eg "%a") that act as placeholders for elements of a story.
Parameters:
- %a => Date accepted (MM/DD)
- %A => Date accepted (YYYY/MM/DD)
- %d => Description
- %D => Description (tabbed once on each newline)
- %e => Estimate
- %i => ID
- %l => Labels (separated by ", ")
- %n => Newline character
- %N => Name
- %o => Owner of the story
- %p => ID of the story's project
- %u => URL pointing to the story
- %t => Tab character
- %T => Type (feature, bug, etc)
Exit Codes
The following is a list of exit codes on various errors for each of the Torque scripts.
General
| Code | Meaning |
|---|---|
| 3 | Invalid arguments |
| 4 | Cannot connect to Pivotal Tracker API |
torque
| Code | Meaning |
|---|---|
| 5 | Missing torque info file |
| 6 | Missing output directory |
| 7 | Missing token |
| 8 | Invalid token |
| 9 | Missing project |
| 10 | Invalid project |
| 11 | Misc. Pivotal Tracker API request error |
| 12 | Misc argument error |
torque config
| Code | Meaning |
|---|---|
| 5 | Pre-existing output directory |
| 6 | Pre-existing torque info file |
| 7 | Invalid output directory |
torque email
| Code | Meaning |
|---|---|
| 5 | Missing torque info file |
torque format
| Code | Meaning |
|---|---|
| 5 | Missing torque info file |
torque project
| Code | Meaning |
|---|---|
| 5 | Missing torque info file |
| 6 | Project not found |
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.