/emacs-scrum

dynamic scrum report generation for org-mode buffers

Primary LanguageEmacs LispGNU General Public License v2.0GPL-2.0

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. 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 report generated from the above file. sections 1.1, 1.2, 1.3, and 1.4 were generated by scrum.el.

here is are example scrum cards.

features

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 LIST (example section 2.3) lists the tasks completed on each day of the sprint. this table also contains the data used to draw the BURNDOWN CHART.

the TASK LIST (example section 2.4; not generated by 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, scrum.el also defines a command (M-x scrum-reset-taskids) that sets task id’s to consecutive values.

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

setup

  1. install emacs
  2. add org-mode to your emacs installation (if you don’t already have it. you probably do)
  3. install gnuplot
  4. get gnuplot.el, add it to your emacs installation
  5. get scrum.el, add it to your emacs installation
  6. copy the template scrum-template.org file to your system and open it in emacs
  7. run “M-x scrum-update-all”
  8. you can export a report using one of the org-export-as-* commands

usage

scrum org file conventions

there are several things that 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, 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:

#+PLOT: title:"Burndown" ind:1 deps:(3 4) set:"term dumb" set:"xrange [0:]" set:"xtics scale 0.5" set:"ytics scale 0.5" file:"burndown.plt"
#+BEGIN: block-update-burndown
#+END:

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

updating generated content

generated content can be updated by running “M-x 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 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 “scrum-taskid-prefix”.

scrum cards

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

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

scrum-taskid-prefix
prefix added to taskids. defaults to “T”
scrum-board-show-owners
if true, show task owners on the scrum board
scrum-board-links
if true, make the items in the scrum board links
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)

todo

  • I’m not sure if gnuplot.el works on windows.
  • org mode treats the ascii graph as a table because of the pipe character borders. prefixing lines with apostrophes helps for ascii export, but html export is a mess.
  • gnuplot shouldn’t have to write the graph to a temp file.