Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
542 lines (418 sloc) 24.5 KB
*rally.txt* Rally ALM Integration for Vim Last change: 2013.11.25
Rally ALM Integration for Vim
v1.1 - 2013.11.25
Rally is an award winning Agile Lifecycle Management (ALM) tool that helps
organizations predictably deliver valuable, quality software. Deliver the
features users love. Faster.
As a vim user, you know what productivity _really_ means. This plugin
lets you collaborate with your agile team using Rally and keep your
fingers on the keyboard.
This plugin continues to be developed out of necessity and is used by
the author. Read some of the interesting |rally-history|.
See the |rally-maintainer| for contact information.
/happy coding/
|rally-requirements| Plugin requirements
|rally-installation| Plugin installation
|rally-configuration| Plugin configuration options
|rally-tutorial| Getting started tutorial
|rally-commands| Available plugin commands
|rally-troubleshooting| Troubleshoot problems with the plugin
|rally-history| Oh the blood, sweat, and tears
|rally-backlog| The infinite todo list
|rally-author| Who on earth wrote this plugin!
* Rally Account: login to
* Rally Workspace: login & confirm access/name of workspace (upper left corner)
* Vim 7.4
- test: $ vim --version | head -1
- note: known minimum version was Vim 7.2p374
- note: the 374 patch provides support for ruby eval() to understand Vim types
- note: patches can be found here:
* Vim compiled with Ruby Support
- test: $vim --version | grep ruby --> look for "+ruby"
- note: you will likely need to pull down source and compile (see Installation)
* Vundle package manager for Vim
* Ruby 2.0: $ ruby --version
- note: this plugin has worked on Ruby 1.8.6+
- note: this plugin was also developed on 1.9.2-p180
- note: I use rvm to manage my own installation of ruby versions; instructions below
* Ruby Gems
- rally_rest_api (1.1.0) # originally developed against 1.0.3
- tzinfo (1.1.0) # originally developed against 0.3.29
- builder (3.1.4) # originally developed against 3.0.0
If you don't see those gems with '$ gem list --local', you can
install them with the following example syntax:
e.g. $ gem install rally_rest_api --version '= 1.1.0'
* [Optional] +clipboard support compiled in to search on
visually selected items.
The Rally plugin requires Vim be compiled with support for Ruby. This may
require that you compile your own version of vim. Sounds scary but,
it can be easy! I've added notes below for my setup in Ubuntu. YMMV.
NOTE: Be sure you already have a Rally account for any edition and can login
from a browser.
0. Requirements - Verify the list of |rally-requirements|
1. Verify ruby support in Vim. If you do not have ruby support, see VIM+RUBY NOTES below.
$ vim --version | grep ruby # need to see '+ruby'
$ vim # launch vim
:ruby puts RUBY_DESCRIPTION # should show ruby 2.0.0 etc
2. Install Plugin with Vundle. If you don't have vundle, see VIM+VUNDLE NOTES below.
* Add "Bundle 'davidpthomas/vim4rally'" to your .vimrc vundle section
$ vim
Note: During installation, vundle will show you a warning/notice to setup
your Rally credentials. Proceed to next step.
3. Setup - Set file permissions and add your connection/login credentials to
the Rally properties file.
* edit ~/.vim/bundle/vim4rally/plugin/ and add your values
* Set the permissions on properties file to 600 or 'rw-------' to
prevent local access. Vim will warn on startup if permissions are not set.
$ chmod 600
4. Documentation - vundle should install the Rally help docs.
Verify the setup by typing ':help rally' within Vim.
5. Verify - Open a file. Type '\h' to see quickhelp commands.
When the plugin is loaded, a connection to
Rally is attempted. You will see an info notice on the
success or failure of that connection. Keep in mind that
the plugin does a lazy 'full' connection to rally
(on first real command) since the first interation takes a
few seconds to cache subscription/workspace details.
With the plugin installed, see the |rally-tutorial| to get started.
Check |rally-troubleshooting| if you encounter any installation problems.
Happy Vimming!
VIM+RUBY NOTES: Compiling Vim with Ruby Support
* Download vim source code
$ sudo apt-get install mercurial # scm tool used by vim
$ hg vim # get vim source code
* Get some dev packages needed to compile
# notes on compiling vim for ubuntu (add'l packages for GUI vim)
$ sudo apt-get install libncurses5-dev libgnome2-dev libgnomeui-dev \
libgtk2.0-dev libatk1.0-dev libbonoboui2-dev \
libcairo2-dev libx11-dev libxpm-dev libxt-dev
* Install ruby 2.0
$ curl -L | bash # install rvm to manage ruby
$ rvm install ruby-2.0.0 # get ruby 2.0
$ rvm --default use 2.0.0 # set ruby 2 as default for rvm
# this sets default ruby binary
$ gem install rally_rest_api builder tzinfo # rally's own ruby gem
* compile vim
$ ./configure --prefix=/usr/local \
--with-features=huge \
--enable-gui=gnome2 \
--enable-rubyinterp \
--with-ruby-command=$HOME/.rvm/bin/ruby # <=== IMPORTANT!
$ make
$ sudo make install
* test vim
$ vim --version | grep ruby # need to see '+ruby'
$ vim # launch vim
:ruby puts RUBY_DESCRIPTION # should show ruby 2.0.0 etc
VIM+VUNDLE NOTES: Installing and setting up vundle
* vundle home:
* obtain vundle
$ git clone ~/.vim/bundle/vundle
* minimal setup to add to your .vimrc
set nocompatible " be iMproved
filetype off " required!
set rtp+=~/.vim/bundle/vundle/
call vundle#rc()
" let Vundle manage Vundle - required!
Bundle 'gmarik/vundle'
Bundle 'davidpthomas/vim4rally'
filetype plugin indent on " required!
* install packages registered in .vimrc
$ vim
:BundleInstall # run this command in vim
The plugin is configured in 'plugin/rally/' file.
base_url: [Required] URL to your Rally subscription
version: [Required] Version of the Rally API to use
username: [Required] Your login name to your Rally subscription
password: [Required] Your password to your Rally subscription # prop file uses secure perms
workspace: [Optional] Default workspace; if empty, will be prompted on first Rally action
log_file: [Optional] Log file for Rally connection
debug: [Optional] enable display of debugging info
prefix_userstory: [Required] Prefix for user stories
prefix_task: [Required] Prefix for tasks
prefix_defect: [Required] Prefix for defects
prefix_defectsuite: [Required] Prefix for defect suites
prefix_testcase: [Required] Prefix for test cases
version: 1.25
password: QuxxPassword
workspace: OurCompany
log_file: /tmp/vim_rally.log
prefix_userstory: US
prefix_task: TA
prefix_defect: DE
prefix_defectsuite: DS
prefix_testcase: TC
Getting Started Tutorial
Open a file and press '\h'. See the available commands? Lets try a
quick search.
[NOTE: If you get an error, see the |rally-troubleshooting| section below].
Press '\s'. Don't know the ID for a story or task? No problem. The
search dialog supports full text searches. Just enter a word that you
know is in one of your stories.
Get some search results? 'j/k' scroll through the list. Find one you
want to see the details of? Just press '\s' again anywhere on the line.
If the story is an epic, down below you'll see a "fold" containing the
children. Just do 'zo' to open the fold and see the children. The idea
is that with folds, we can show children stories, discussion threads,
revision history, etc. in a small amount of space. Back on track, scroll
down and hit '\s' on leaf level story. That will open.
On a leaf story, scroll down and look for tasks (if it has some). Again,
another fold, so 'zo' to open it up. press '\s' on a task.
In a task, you have some options to edit data. For example, to change
the 'to do' field, press '\tt' (task todo). To edit the estimate,
press '\te' (task estimate). To toggle the blocked status, press '\tb'.
Lastly, check out the charts. To see a burndown chart, press '\cb'
(chart burndown) or '\cc' (chart cumulative flow).
Taking a step back, the '\s' lets you search for stories, tasks, and
defects. Just press that, enter an ID or a search string. You can
review the details and possibly update the tasks. That's it!
Take a look at the inline help with '\h'. Those are all available
\h - Rally 'quick' help
This will show an inline list of key commands with brief description.
\z - Rally Information
This will show information about the current connection such as
workspace, user, etc. If debugging is enabled in the
file, this will show even more info such as per-window details.
\w - Rally Workspace [Switcher]
Prompts the user to select a new workspace. This workspace will be
loaded (and cached).
\s - Search
One of the most powerful aspects of this plugin is context-aware search.
No matter where you are, '\s' will react to visual mode selections, current
line, scan for Ids, and prompt for criteria if no context is found.
Searching may return a single artifact or multiple, mixed results.
The algorithm is as follows:
[visual mode?] [normal mode?]
grab all selected text grab current line
\ /
\ /
\ /
empty results?
| \
| [Yes]
[No] \
| Prompt User for search string
text contain artifact Id? (US123, DE456, etc)
/ \
[Yes] [No]
/ \
Single Artifact Search General Text Search
(display details) (display multiple results)
\tt - Task Todo (update)
This command will prompt to update the ToDo hours for a task. The plugin
will attempt to find the a task in context from the task details page
or task ID on current line. Otherwise, it will prompt for the task ID.
\te - Task Estimate (update)
This command will prompt to update the Estimate hours for a task. The plugin
will attempt to find the a task in context from the task details page
or task ID on current line. Otherwise, it will prompt for the task ID.
\tb - Toggle Task Block (update)
This command will prompt to toggle the BLOCKED state of a task. The plugin
will attempt to find the a task in context from the task details page
or task ID on current line. Otherwise, it will prompt for the task ID.
\cb - Iteration Burndown Chart
This command will show the burndown chart for the currently selected
\cc - Iteration Cumulative Flow Diagram
This command will show the cumulative flow diagram for the currently
selected iteration.
Symptom: Error loading plugin when starting vim.
Error message may include:
* no such file to load -- rally_rest_api
* no such file to load -- builder
Solution: Install the required gems.
e.g. $ gem install rally_rest_api --version '= 1.0.3'
e.g. $ gem install builder --version '= 3.0.0'
Symptom: Warning messages about required or not-found property values.
Solution: Verify that plugin/rally/ exists. Inside
the file, verify that all properties have values set.
base_url: URL to Rally subscription e.g.
version: Version of the web service API e.g. 1.25
username: Your Rally subscription username
password: Your Rally subscription password
workspace: Rally workspace to connect to
Symptom: Warning message about Rally properties file at vim startup.
Solution: If your plugin/rally/ file is visible to other users,
the Rally plugin will show a warning message. Be sure to set the
permissions of this file to 600 or 'rw-------'.
Unix: $ chmod 600
Windows: Good luck with security. FIXME
Symptom: Rally help documentation not loading.
Solution: Verify that the rally.txt file is located in the vim /doc
Unix: $HOME/.vim/doc/rally.txt
Windows: %HOMEPATH%\vimfiles\doc\rally.txt
Install help documentation by launching Vim and executing:
Unix: :helptags ~/.vim/doc
Windows: :helptags ~\vimfiles\doc
Verify that the help docs are available by launching vim then typing
":help rally".
Plugin Development History
Most of the plugin development happened while I was traveling; either
waiting at an airport, 30,000+ feet above sea level, or in a hotel room.
I also spent spare cycles during evenings/weekends at home in Santa Cruz, CA.
2011 Feb 07 37kft: SJC>DEN: initial project concept
2011 Feb 17 35kft: DEN>SJC: User: launch new window to show results
2011 Apr 29 41kft; PDX>SJC: spike ruby control of vim
2011 May 09 37kft; SJC>DEN: spike ruby control of vim
2011 May 13 36kft; DEN>SJC: runtime lib loading
2011 Jul 28 36kft; SJC>DEN: login auth
2011 Jul 30; Boulder,CO: login auth and password security
2011 Jul 31; Boulder,CO: story details page - initial data
2011 Aug 01; Boulder,CO: story details page - layout
2011 Aug 02; Boulder,CO: story details page - children and attribute type query
2011 Aug 03; Boulder,CO: story details page - children display
2011 Aug 03 36kft; DEN>SJC: plugin load performance; progress bar
2011 Aug 06; Santa Cruz, CA: plugin load performance; progress bar
2011 Aug 07; Santa Cruz, CA: plugin load performance & latestrapping; properties as ruby not vim
2011 Aug 09; Santa Cruz, CA: story tasks
2011 Aug 10; Santa Cruz, CA: story defects
2011 Aug 11; Santa Cruz, CA: story discussion threads
2011 Aug 20; Santa Cruz, CA: generalized story search
2011 Aug 21; Santa Cruz, CA: refactored search and content views
2011 Aug 22; Santa Cruz, CA: refactored search and content views
2011 Aug 28; Santa Cruz, CA: implemented erb templates for views; using ws timezone for discussions display
2011 Sep 03; Santa Cruz, CA: search in visual mode; search algorithm
2011 Sep 04; Santa Cruz, CA: displaying multiple search results
2011 Sep 16; 34kft; SJC>SAN: spike dashboard views with vim tab framework
2011 Sep 17; San Diego, CA: window management for search results
2011 Sep 08; Santa Cruz, CA: info window
2011 Oct 15; Santa Cruz, CA: debugging details in info window
2011 Oct 16; Santa Cruz, CA: refactored vim/ruby include framework to make ruby code independently testable (removed ruby << load syntax); refactored autoload mechanism to reduce LOC
2011 Oct 18; Santa Cruz, CA: reload/refresh of details after task todo updated; framework for reloading
2011 Oct 19; Santa Cruz, CA: workspace chooser / reload incl. picker widget; refactored connection workspace caching
2011 Oct 22; Santa Cruz, CA: quick help display; simplified key bindings; added usability text tips for \help
2011 Nov 03; Santa Cruz, CA: refactor view code to share formatting logic
2011 Nov 28; 37kft; SFO>DEN: added console and gui menus
2011 Dec 27; Santa Cruz, CA: fixed visual bug in text search
2011 Dec 28; Santa Cruz, CA: added date labels on burndown chart horiz axis; finished first pass at burndown chart
2012 Jan 02; Santa Cruz, CA: added task est update and task block toggle; refactored quickhelp; refactored use of _refs for code usability
2012 Jan 03; Santa Cruz, CA: added case insensitive formatted id search; fixed iteration lookup in statusbar
2012 Jan 05; Santa Cruz, CA: added cumulative flow diagram
2012 Jan 06; Santa Cruz, CA: added parent id to story display to navigate up
2012 Jan 07; Santa Cruz, CA: release 1.0-RC1
2012 Feb 09; Santa Cruz, CA: error handling if +clipboard not compiled in for visual searching
2012 Apr 24; Santa Cruz, CA: created github repo
2012 Apr 26; Santa Cruz, CA: 1.0 release
2013 Nov 23; 37kft; DEN>SJC: researching vundle
2013 Nov 24; Santa Cruz, CA: fixed runtime load paths to support vundle
2013 Nov 25; Santa Cruz, CA: updated docs; release
Open Backlog of Work
B=Backlog, P=In Progress, C=Completed, A=Accepted
E=Epic, T=Task
A User, I want the plugin to auto-load when vim starts to prevent manual startup per session [02/07/2011]
A User, I want an inline help guide describing the plugin to read a description and history [02/07/2011]
A User, I want the plugin to load in multiple open buffers
A User, I want to know if my version of Vim needs upgraded to be compatible with the Plugin
A User, I want to know what version of the plugin is currently loaded
A Spike: ruby integration in vimscript
A User, I want to auto-login by [securely] storing credentials in plugin script
A User: I want to load a story by ID to review the details during development
A User: I want most of the story details to show in the window
A User: progress bar for plugin onload
A Plugin: convert properties file from vimscript syntax to ruby yaml
A User: I want the plugin to load after vim so I can immediately begin editing the file and not waiting on rally connect/setup
A User: async load on startup to prevent delays
A User: I want to view tasks on a story
A User: Minimize data showed in story to prevent scrolling
A User: search for story by id when cursor is over id
A User: show discussion threads
A User: search by highlighted text
A User: text search for multiple items
A doc req't /install on rally rest gem
A User: single display to prevent opening too many windows
A User: show cutline ; change highlighting via article
A Plugin: display rally and debugging info in a window
A Plugin: make ruby code independently testable by ruby-only framework (outside of vim)
A User: ability to update task todo hours
A User: refresh details display if task todo updated
A User: select workspace
A Plugin: consider replacing runtime/GOTRUBY with rubyfile {file}
A Plugin: rename rally global var to conn ? to prevent rally.rally calls in model
X User: allow CTRL-C interruption and cancel of an operation
A User: show workspace info in status bar
A Plugin, consolidate all g:vim rally vars into hash
A User, I want an installation guide
A User, show 'quick help' page with keys
A User, search and show defect details
A User, show story id in tasks to navigate 'upwards'
A Plugin: refactor view templates to share formatting code
A User, show custom menus in console and gvim with avail options
A User, show burndown chart
A User, update task estimate
A User, toggle task blocked
A User, show cumulative flow diagram for current iteration
<^^^^^^^^^^^^^^[dev cutline]^^^^^^^^^^^>
B Plugin: remove /slm suffix from properties file; make internal
B User, support for portfolio items
B [bug] Plugin, only resize active charts
B User, add/delete tasks
B User, show and select iteration on burndown chart
B User, show project name in status bar
B User, show tooltip during load splashscreens
B Plugin Developer, I want to display debugging information as the script loads to visualize progress / errors
B User: unload rally plugin back to initial state (e.g. statusline)
B Plugin: separate syntax files; enable/disable depending on content shown; prevent match conflict (e.g. Name, Est)
[B]acklog | [P]rogress | [A]ccepted | [X] cancelled
Plugin Author/Maintainer
David P Thomas, <>
personal blog:
* Vim user since 1997 (pico before that ;)
* currently a Technical Account Manager at Rally Software (2010-present)
* formerly a Senior Systems Engineer at AccuRev (2006-2010)
* formerly a Senior Software Engineer at (2001-2006)
* author of vim plugins for accurev and rally
* numbers juggler, 5 & 7 balls
* snowboarder with instructor certification (CASI / Whistler)
* Unix over Windows; Vi over Emacs; Ruby over Java; 95wpm.
* father of two young sons who enjoy pointing at green screen terms
* living, running, and mountain biking in Santa Cruz, CA
Feel free to contact me with feedback/questions/comments!
-- dave,