Quickstart Guide

Deft is a tool for Easy Distributed Feature Tracking. It records features in plain-text files that can be easily stored in a (distributed) version control system alongside the system's source code. It's distinguishing feature is that it stores features in absolute priority order and lets you easily change those priorities.

Creating a Feature Tracker

To create a tracker, use the command:

% deft init
initialised Deft tracker

This will create a directory called .deft/ to store private configuration files and information about the tracked features.

If you want the tracked features to be stored in a directory that is easier to work with (e.g. not in a hidden directory), you can specify the data directory when the tracker is initialised. For example, the following command will create a tracker that stores features in the directory deft-tracker:

% deft init -d deft-tracker
initialised Deft tracker

Creating Features

A Deft "feature" tracks some feature of the software from desire to delivery. It may be new functionality, changes to existing functionality or a bug that needs fixing.

A new feature is recorded with the deft create command. The minimum amount of information you need to specify for a new feature is [a short, human-readable name](Naming Features) and a detailed description. For example, the following command creates a new feature called shiny-buttons and launches a text editor in which you can enter the description:

% deft create shiny-buttons

We can see the current status of the feature with the deft list command:

% deft list
new 1 shiny-buttons

This shows that the shiny-buttons feature is in the new state and has priority 1. All features have a status and priority. The status tracks the progress of the feature through the development process. All issues with the same status have a unique priority, with 1 being highest priority.

Let's create a couple more issues:

% deft create smooth-animations
% deft create irritating-sounds
% deft list
new 1 shiny-buttons
new 2 smooth-animations
new 3 irritating-sounds

Now we can see that all issues have status new, and that smooth-animations has priority 2 and irritating-sounds has priority 3. Unless told otherwise (as we'll see below), Deft adds new features at the bottom of the prioritised list.

Feature Status

Let's start work on the shiny-buttons feature. We record this with the deft status command:

% deft status shiny-buttons work-in-progress

Now our repository looks like this:

% deft list
work-in-progress 1 shiny-buttons
new              1 smooth-animations
new              2 irritating-sounds

We can see that the shiny-buttons has the status work-in-progress. It is the only work-in-progress feature and so has been given priority 1. The remaining new features are prioritised from 1.

We can let other people see we've started working on the feature by pushing our updated feature database to our shared Git repo:

% git commit -a -m "started working on shiny-buttons"
% git push

Note: this example assumes everyone works on the mainline, where developers make frequent commits as they develop the feature they're working on, and make sure the mainline is always in a working state. The Deft workflow would be different if you use long lived feature branches, in which development of an entire feature is done away from the mainline and merged back in when complete.

Deft does not constrain how statuses are named or the valid transitions between statuses: it's up to you to choose them to reflect how you work on your project. If you need to, you could enforce your chosen constraints with commit hooks in your version control system.

When we're happy with our implementation we can set the feature status to reflect this and push our changes to both the code and feature tracker into the main repo.

% deft status shiny-buttons implemented
% git commit -a -m "shiny buttons fully implemented"
% git push

Feature Priority

As we've seen, Deft orders all features by priority. You can change priorities with the deft priority command.

Let's add some more features to our tracker.

% deft create twitter-tweeting
% deft create facebook-poking
% deft list --status new
new 1 smooth-animations
new 2 irritating-sounds
new 3 twitter-tweeting
new 4 facebook-poking

Deft has added those features at the bottom of the priority list. Our marketing director is adamant that these are vital features of any modern piece of software. Let's move them to the top two priorities and put facebook-poking at number 1.

% deft priority facebook-poking 1
% deft priority twitter-tweeting 2
% deft list --status new
new 1 facebook-poking
new 2 twitter-tweeting
new 3 smooth-animations
new 4 irritating-sounds

We can also specify the priority of a new feature when we create it. Our marketing director also wants our app to integrate with Live.fm, but it's not as important as our app having smooth animations. However it is slightly more important than our app making irritating sounds on public transport. We'll create our new feature with priority 4, pushing irritating-sounds down to priority 5:

% deft create livefm-scrobbling --priority 4
% deft list --status new
new 1 facebook-poking
new 2 twitter-tweeting
new 3 smooth-animations
new 4 livefm-scrobbling
new 5 irritating-sounds

That feature list will make our app the ideal mobile web2.0 ajax iOS mash-up hot property. It's only a matter of time before our start-up is acquired and we can finally leave Shoreditch and go live by the beach in the Bahamas.

Where Next

For a list of all Deft commands and options, use the command deft --help. To get help on a specific command, use deft <command> --help. For example, deft list --help.

Ideas about different Deft Workflows.

You can configure the Initial Status of New Features to support your workflow.