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.
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.
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.
- install emacs
- add org-mode to your emacs installation (if you don’t already have it. you probably do)
- install gnuplot
- get gnuplot.el, add it to your emacs installation
- get scrum.el, add it to your emacs installation
- copy the template scrum-template.org file to your system and open it in emacs
- run “M-x scrum-update-all”
- you can export a report using one of the org-export-as-* commands
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.
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
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.
- 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
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:
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.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”
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)
- 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.