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

run M-x package-install RET org-scrum

manual install

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

setup

install gnuplot
copy the template scrum-template.org file to your system and open it in emacs
run M-x org-scrum-update-all
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.

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
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.
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-show-owners

if true, show task owners on the scrum board

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)

jstitch / emacs-scrum