Precis
The idea is to allow for Kanban boards to be stored in Git. This means that a Git ref will store all the cards, lanes, milestones, and other metadata associated with a board. Then using a git commit chain as the "changelog" we can perform actions on the board by editing files and committing them.
Ideally the layout will be conducive to allowing for offline updates to then be easily merged into the shared instance at a later point.
First class objects and their properties
Cards
Cards are individual items in the Kanban. They are meant to represent chunks of work to be done, but could equally represent bugs or other things.
A card has a UUID, of the form cards/XXXXXXX
They have a number of required properties:
- title (short title)
- description (longer description)
- lane (UUID of the lane they're in)
- archived (Whether or not this card is archived from the board)
They may have the following properties also
- milestone (UUID of the milestone they're against)
- assigned (Name of someone they're assigned to)
- duedate (Specific due date for the card)
- tags (Arbitrary tags for the card, useful for searching/limiting etc)
Lanes
Lanes are groupings of cards. They have a few properties of their own and otherwise are entirely defined by the set of cards within them. Each card indicates which lane it is in, and this is considered the canonical source of that information.
A lane has a UUID, of the form lanes/XXXXXXXX
They have a number of required properties:
- name (short name)
- description (explanation of the lane)
- priority (rough position of the lane, integer, may be negative)
- finished (if cards in this lane are considered finished)
They have optional properties including:
- colour (colour for cards in this lane which are not milestoned)
Lanes also contain an ordered list of the UUIDs of all the cards in them.
Milestones
Milestones are an optional grouping of cards, typically representing a deadline or feature goal.
A milestone has a UUID, of the form milestones/XXXXXXXX
Milestones have a number of required properties:
- name (short name)
- description (description of the milestone)
- deadline (date on which the milestone is due)
- archived (Whether this milestone is archived, i.e. hidden)
They have optional properties including:
- colour (colour for cards against this milestone (overriding lane colour)
Notes related to those objects
Normalising lane contents
When a card is put into a lane (by setting its lane property) the lane doesn't necessarily know about it. During normalisation of the board, the lane's list of cards is updated. Cards which no longer claim to be part of the lane are removed from the lane and cards which newly claim to be part of the lane are added at the bottom of the lane in asciibetical-by-UUID order.
Operations which users perform on a board
Lane related operations
- Adding lanes to a board
- Renaming/reordering lanes (changing lane properties)
- Deleting lanes from a board
- Moving cards within a lane
Milestone related operations
- Adding milestones to a board
- Altering milestone properties
Card related operations
- Adding cards
- Altering non-structural properties (title, description, assignedto etc)
- Moving cards between lanes
- Assigning cards to milestones
- Deassigning cards from milestones
Storing the kanban in a Git tree
Given the UUIDs are of the form type/XXXXXXXX they easily fit into the idea
of a filesystem tree. The UUIDs will be short, likely something easily
remembered, so whatever tool manipulates the kanban will choose sensible ones.
As such, each object will be a simple text file in a file in a tree of the form implied by the UUIDs. The format of the text file will be RFC822 style key-value pairs, with keys ordered asciibetically.