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 tasks arranged in columns based on their TODO status. scrum board labels can be plain text or links to the items in the tree.

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

ESTIMATED

total estimated time of their tasks

ACTUAL

total actual time they spent

DONE

sum of estimated time for tasks they’ve completed

REMAINING

sum of estimated time for tasks not yet completed

PENCILS DOWN

date on which they expect to complete their tasks

PROGRESS

percent of their tasks 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 TASK LIST (example section 2.4; not generated by org-scrum.el, it’s just a columnview) provides the following info for each task:

TASKID

identifier for the task

OWNER

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

ESTIMATED

hours the task owner thinks the task will require

ACTUAL

hours spent on the task

for convenience, org-scrum.el also defines a command (M-x org-scrum-reset-taskids) that sets task id’s 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

if you’re upgrading from version 0.0.x, note that the block-update-burndown secion is no longer used. you should remove it from your file.

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.

boilerplate header block

add this block at the top of the file. it defines some parameters that org-mode uses when it exports, defines the TODO states here, and creating the OWNER, ESTIMATED, and ACTUAL properties for tasks.

#+TITLE: [your report title]
#+AUTHOR: [your name]
#+EMAIL: [your email address]
#+COLUMNS: %35ITEM %TASKID %OWNER %3PRIORITY %TODO %5ESTIMATED{+} %3ACTUAL{+}

the columns of the scrum board are based on the TODO keywords, which can be set in the header as well.

#+TODO: TODO STARTED | DONE DEFERRED

meta data

to generate the report artifacts, org-scrum.el needs to know where to find your task data, how many developers are on the team, and the sprint schedule. we’ll add all those things as properties of the root headline of the tasks tree.

1. the root headline must have the following properties:

   ID

   set to “TASKS”

   SPRINTLENGTH

   the number of days in the sprint

   SPRINTSTART

   the date on which the sprint begins

2. the root headline must have a property for each developer specifying their name and the number of hours per day they expect to work on this project. names should be prefixed with “wpd-“. for example, “:wpd-ian: 3” mean ian is expecting to work on this project for 3 hours per day.
3. tasks (headlines with TODO’s) should have OWNER ESTIMATED and ACTUAL properties.

   OWNER

   list of space delimited developer names. the first name is considered the owner of the task.

   ESTIMATED

   a task owner’s time estimate in hours

   ACTUAL

   the number of actual hours spent

report blocks

the generated content is written to dynamic blocks embedded in the same org file on 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.

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

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

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

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

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 a dynamic block #+BEGIN line.

M-x org-scrum-reset-taskids will set all task 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-taskid-prefix.

scrum cards

org-scrum.el can generate a pdf (requires texi2pdf, and multirow.sty) of task cards that can be printed out and stuck on a physical scrum board. each card contains the task’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-taskid-prefix

prefix added to taskids. defaults to “T”

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 as

• 1. id.
• 2. priority task (closedate)
• 3. id. priority task (closedate)
• 4. id. owner (closedate)
• 5. id. priority task (owner closedate)