First Steps

by Richard Taylor : 2019-10-21

OK. We know what we want. Roughly. So where do we start?

Let's do this in an Agile way. We wont design everything up front, because we only have a rough idea of what we want. Start with what we know, lay down some basic principles, then build a minimal prototype.

First Principles

The goal of the project is to connect and map whatever items you need to track.

So that gives us a number of concepts to consider:

• Connections
• Maps
• Items
• People
• Tracking

We can explore each of these and make some initial notes on their most important properties.

Item

As I mentioned in the introduction, this project aims to support many different types of item. Off the top of my head I can think of:

• requirement
• epic
• story
• task
• bug
• commit
• test case
• test suite
• document
• peer review
• release

And there will be more. So an important feature will be that we must be able to extend the set of item types at any time.

We also want to be able to map these items. Which implies that all items must have properties or labels that can be mapped to numerical values.

Connection

A connection is a link between items. There are all sorts of different connections I can think of; for example:

• satisfies
• implements
• explains
• blocks
• affects

And many more. So, as with items, we must be able to extend the set of link types at any time.

People

Items and connections are created and managed by people. We need to represent that, so we can track who did what and when.

Map

This is the biggest unknown at this stage. I talked about maps being different from graphs in the introduction, but what can be usefully mapped is still open and will require some experimentation and more thought.

Tracking

Perhaps the most important requirement is tracking. If you have ever worked in a safety critical environment then you will know how strict the auditing is. And that level of discipline could be very useful in "ordinary" projects too, if it was easier to apply.

Some of the implications of strong tracking are:

• All entities have immutable fields like "creator" and "creation time"
• All changes are fully logged

Which means that "the log is the database" is an option. In other words, there has to be enough information in the log to reproduce the data, so why do you need a separate database? [answers on a postcard]

It is also worth considering making all operations reversible up front, since adding "undo" functionality later is always a pain.

First Version

To get something working quickly I am going to focus on an API to build and connect items. It will use an in-memory store and log all the changes.

I will write a set of tests to exercise the API from different "client" perspectives.

Then, in later versions, I will consider persistent storage and user interfaces.