org scrum

overview

emacs is a text editor. an extensible one. it is mainly used for coding, but it can also do anything else. org-mode is an extension to emacs that provides a simple way to manage todo lists, organize notes, or maybe do some project management.

scrum is an agile process for software development. org-scrum.el is an extension to org-mode that generates tables and burndown charts that may be helpful to a scrum team. all generated content is based on the existing content of the org buffer.

example

here is an example org file.

here is an example ascii report generated from the above file. here is the same thing exported as html. sections 1.1, 1.2, 1.3, and 1.4 were generated by org-scrum.el.

here is an example of generated scrum cards.

features

org-scrum.el generates the following:

a SCRUM BOARD made up of the stories arranged in columns based on their TODO status. scrum board labels can be plain text or links to where the items are defined in the document.

the DEVELOPER SUMMARY table (example section 2.1) provides the following info for each developer:

ESTIMATED

total estimated points of stories assigned

ACTUAL

total actual points of stories assigned

DONE

sum of estimated points for stories they’ve completed

REMAINING

sum of estimated points for stories assigned but not yet completed

PENCILS DOWN

date on which they expect to complete all assigned stories

PROGRESS

progress bar showing percent of their stories that are done

the BURNDOWN CHART (example section 2.2) shows actual progress against a smooth completion rate. the burndown chart can be ascii or an embedded image, and the size can be customized (see the org-scrum-ascii-size and org-scrum-image-size variables). if the graph is an image and you want emacs to display it automatically when you open the file, enable org-startup-with-inline-images.

the STORY LIST (example section 2.4; not generated by org-scrum.el, it’s just a columnview) provides the following info for each story:

STORYID

identifier for the story

OWNER

list of developers that are assigned to the story. the first name is considered the owner.

PRIORITY

priority assigned to the story

TODO

the story’s scrum board status

ESTIMATED

story point estimate

ACTUAL

optional revised story points

the SPRINT PROGRESS section contains a graph of stories linked to dependencies. this can help to determine in which order stories need to be taken up. Stories are also colored from light to dark depending on their current TODO state so this graph also gives a view into overall progress.

the SPRINT PLANNING table uses developer capacity and points completed to calculate the team’s velocity. velocity is the average number of estimated hours completed over the last six sprints. then it uses velocity to estimate how many points can reasonably be completed next sprint.

for convenience, org-scrum.el also defines a command (M-x org-scrum-reset-storyids) that sets story ids to consecutive values.

org-scrum.el can also create a pdf for printing out cards for sticking on a physical scrum board.

installation

melpa

1. run M-x package-install RET org-scrum

manual install

1. download uml-mode.el
2. run M-x package-install-file RET
3. choose org-scrum.el

setup

1. install gnuplot
2. copy the template scrum-template.org file to your system and open it in emacs
3. run M-x org-scrum-update-all
4. you can export a report using one of the org-export-as-* commands

upgrading

breaking changes

there were breaking changes from 0.1.x to 0.2.0. the recommended approach to upgrading is to start from a new template.

functional changes from version 0.1.x

before version 0.2.0 the entire org-scrum file was for a single sprint. all tasks were assigned to that sprint and developer capacity was fixed.

with version 0.2.0 org-scrum tracks tasks and progress through multiple sprints. tasks can be assigned to sprints and are cleared from the sprint board when they are completed and the next sprint begins. developers can provide capacity numbers for future sprints which, along with velocity calculations, enable org-scrum to project how much should get done in the upcoming sprint.

in scrum, work is captured in stories which are estimated in points and then broken down into tasks which are estimated in hours. before 0.2.1 the unit of work for org-scrum was a task. going forward org-scrum works at the story level.

file structural changes from 0.1.x

before 0.2.0 sprintlength, sprintstart and the list of developers and their capacities (which was called wpd) were saved as properties in the TASKS headline. these have been moved out into the #+CONSTANTS parameter and capacity table.

before 0.2.0 the burndown chart block name was block-update-graph. it has been renamed block-update-burndown.

property drawers containing CUSTOM_ID were added to each of the report sections.

before 0.2.1 the work to be done was entered into the tree with parent node ID = TASKS. going forward the parent node ID must be STORIES.

usage

scrum org file conventions

there are several things that org-scrum.el expects to find in the org file on which it is running. if something is missing, it will let you know. it is best to start from the example template, but the requirements are described in this section.

boilerplate header block

add this block at the top of the file. it defines some parameters that org-mode uses when it exports.

#+TITLE: [your report title]
#+AUTHOR: [your name]
#+EMAIL: [your email address]

this line defines the TODO states, which will also be the columns of the scrum board. modify this line to add or remove scrum board columns.

#+TODO: TODO STARTED | DONE DEFERRED

this line defines the columns that will be included in the STORY LIST report. these are also the story properties and the columns that will be shown for the story tree when in columnview mode. the columns are described below in the stories bullet in the section on metadata. it is safe to rearrange these items but removing something might break some reports.

#+COLUMNS: %35ITEM %STORYID %OWNER %3PRIORITY %TODO %5ESTIMATED{+} %3ACTUAL{+} %SPRINT %DEPS %SWIMLANE

this line provides some styling to reports exported to HTML.

#+HTML_HEAD: <style>table { width: 100%; border: 1px solid; } th, td { border: 1px solid; } table th { background-color: #f2f2f2; } div#outline-container-summary table td:last-child { font-family: monospace; text-align: center; } div#outline-container-capacity table tbody:last-child { font-weight: bold; background-color: #f2f2f2; }</style>

metadata

to generate the report artifacts, org-scrum.el needs to know where to find your story data, how many developers are on the team, and the sprint schedule. to accomplish this,

1. the root headline must have a property ID which is set to “STORIES”
2. there must be a #+CONSTANTS: entry that sets

   sprintlength

   the number of days in the sprint

   sprintnum

   the number of the current sprint

3. there must be a capacity table with the rows

   sprint

   sprint number

   start

   the date on which that sprint begins

   developers

   hours of daily capacity for each sprint

   total

   total capacity

4. stories (headlines with TODO’s) should have several properties that org-scrum uses to build its reports. use M-x org-columns to easily view and edit these properties.

   STORYID

   a unique identifier for each story

   OWNER

   a space delimited list of developers names. the first name is considered the owner of the story.

   ESTIMATED

   estimated story points

   ACTUAL

   revised story points (this allows you to note when stories were mis-estimated without being tempted to change the original estimate)

   SPRINT

   the number of the sprint to which this story is assigned

   DEPS

   a space delimited list of STORYIDs on which this story depends

   SWIMLANE

   assign stories to different swimlanes to indicate where there are consecutive steps that can be taken by different developers or teams.

report blocks

the generated content is written to dynamic blocks embedded in the same org buffer in which it is operating. org-mode needs those blocks to have #+BEGIN and #+END statements so that it knows where to write the generated content. to that end, this needs to be somewhere in the file for each report. however, the order that they occur in the file doesn’t matter and all report sections are optional. if a report block is not found in the buffer, org-scrum-update-all will skip them.

#+BEGIN: block-update-board
#+END:

#+BEGIN: block-update-summary
#+END:

#+BEGIN: block-update-burndown
#+END:

#+BEGIN: block-sprint-progress
#+END:

#+BEGIN: columnview :hlines 2 :maxlevel 5 :id "STORIES"
#+END:

schedule and capacity table

the schedule and capacity section contains two important things.

the sprintlength and sprintnum constants can be updated directly. simply edit them inline and use C-c C-c to load the setting.

the capacity table can be used to add or remove sprints by adding or removing columns. the first row identifies the sprint number and is autogenerated (changes will be overwritten). you can also set sprint start dates by editing the second row (changes here will not be overwritten). alternatively if you blank cells in the second row and run the table formula it will fill them in by adding sprintlength days to the previous sprint start date. you have to set the first sprint’s start date.

you can also use it to add or remove developers by adding or removing rows in the center section between the hlines. finally, the capcity table can be used to set developer capacity by filling in the numbers in the sprint rows between the hlines. capacity is in hours of work per week. running the table formula will recalculate the total, but you don’t have to do this manually since it is done automatically by org-scrum-update-all. you can run the table formula by hitting C-c C-c on the TBLFM: line at the bottom of the table.

updating generated content

generated content can be updated by running M-x org-scrum-update-all

alternatively, individual blocks can be updated by doing a C-c C-c with the point on the #+BEGIN line at the top of the block.

run M-x org-scrum-start-next-sprint to start the next sprint. this command will increment the current sprint number and reassign all of the stories that are in the current sprint and not done to the new sprint.

M-x org-scrum-reset-storyids will set all story id’s to consecutive values for the tree at the point. the values are two digits starting from one and prefixed with the string given by the variable org-scrum-storyid-prefix. this is deprecated and will be altered or removed in future versions.

scrum cards

org-scrum.el can generate a pdf (requires texi2pdf, and multirow.sty) of story cards that can be printed out and stuck on a physical scrum board. each card contains the story’s id, owner, estimate, actual, and headline text. the pdf will be named “scrum_cards.pdf”

customization

org-scrum.el defines several variables that can be used to customize the content it generates.

org-scrum-ascii-graph

if t export the burndown graph in ascii, else use an embedded svg image

org-scrum-ascii-size

for ascii burndown graphs, size as (width height)

org-scrum-image-size

for svg burndown graphs, size as (width height)

org-scrum-storyid-prefix

prefix added to story ids. defaults to “S”

org-scrum-board-links

if true, make the items in the scrum board links

org-scrum-board-format

specify the format of the scrum board items. this accepts a format string that supports the following replacements

%i

story id

%p

priority

%t

story title

%o

story owner(s)

%c

close date

this still supports the following legacy formats which can be set by number

1

id.

2

priority title (closedate)

3

id. priority title (closedate)

4

id. owner (closedate)

5

id. priority title (owner closedate)

org-scrum-progress-colors

specify the mapping of TODO state to color to use for it in the progress graph.