Issue tracking with Ditz: a walkthrough
When it comes to tracking code issues (tasks/features/bugs) I’ve never been truly satisfied with the tools on offer. After using Trac for a long time, and switching to Lighthouse only recently, I still wasn’t happy: they are just too divorced from the code for me (despite the VCS hooks, e-mail client
integration, etc.).
I began to track certain type of issues in the code instead, using a custom Rake task that found and collated them all (just as ‘rake notes’ does for a Rails application).
Then I came across Ditz, a command-line issue tracker. Switching between code and issue management just got super quick. It’s easy to add new issues, assign them to specific people/releases/branches, track progress, and lots more. Everything you’d expect really - but it stores all of the issues in the repository itself, as flat files (YAML).
Try it for yourself! Here’s a quick primer on how to install it, use it, and have it play nice with Git:
Install:
$ sudo gem install ditz
Use:
$ cd projectxThis will walk you through your user and project setup. Trust me, it’s easy and obvious, but I’ll include an example here for those of you who aren’t following along!
$ ditz init
I wasn't able to find a configuration file ./.ditz-config. We'll set it up right now. Your name (enter for "Karl"): Your email address (enter for "karl@example.net"): Directory to store issues state in (enter for "bugs"): issues Project name (enter for "projectx"): Issues can be tracked across the project as a whole, or the project can be split into components, and issues tracked separately for each component. Track issues separately for different components? (y/n): y Current components: None! (A)dd component, (r)emove component, or (d)one: a Component name: gui Current components: 1) gui (A)dd component, (r)emove component, or (d)one: a Component name: payments Current components: 1) gui 2) payments (A)dd component, (r)emove component, or (d)one: a Component name: user Current components: 1) gui 2) payments 3) user (A)dd component, (r)emove component, or (d)one: d Ok, issues directory created successfully.
With that done, let’s add an issue!
$ ditz add
Title: Don't forget to do this task! Description (ctrl-d, ., or /stop to stop, /edit to edit, /reset to reset): > Task description > /stop Is this a (b)ugfix, a (f)eature, or a (t)ask? t Choose a component: 1) projectx 2) gui 3) payments 4) user Component (1--5): 4 Issue creator (enter for "Karl "): Comments (ctrl-d, ., or /stop to stop, /edit to edit, /reset to reset): > ^D Added issue user-1. You may have to inform your SCM that the following files have been added: issues/issue-f87a61786e74f311d8653f03ecb9091ff8cf96b7.yaml
Take note of that last line, we have an automated solution for that later!*
Now, let’s see what we’ve got:
$ ditz
Unassigned: _ user-1: Don't forget to do this task!
$ ditz show user-1Issue user-1 ------------ Title: Don't forget to do this task! Description: Task description Type: task Status: unstarted Creator: Karl <karl@example.net> Age: three minutes Release: References: Identifier: f87a61786e74f311d8653f03ecb9091ff8cf96b7 Event log: - created (karl, three minutes ago)
Great. Now, all main operations in Ditz are time-stamped; this means that you can see the latest activity by just:
$ ditz log
date : Thu Aug 28 21:47:32 +0100 2008 (six minutes ago) author: Karl <karl@example.net> issue: [user-1] Don't forget to do this task! created
Okay, let’s create a release to assign issues to.
$ ditz add-release
Name: 0.0.1 (Initial Alpha) Comments (ctrl-d, ., or /stop to stop, /edit to edit, /reset to reset): > ^D Added release 0.0.1 (Initial Alpha). You may have to inform your SCM that the following files have been modified: issues/project.yaml
Every issue is internally stored against a project-wide unique ID (like Git’s commit hashes). Also (like Git), you can address these easier than using this hash. For example, our recently added issue is called user-1.
Let’s assign it to our initial release.
$ ditz assign user-1Issue user-1 currently not assigned to any release. Choose a release: 1) 0.0.1 (Initial Alpha) (unreleased) Release (1--1): 1 Comments (ctrl-d, ., or /stop to stop, /edit to edit, /reset to reset): > ^D Assigned user-1 to 0.0.1 (Initial Alpha). You may have to inform your SCM that the following files have been modified: issues/issue-f87a61786e74f311d8653f03ecb9091ff8cf96b7.yaml
Listing the issues now reflects this.
$ ditz
0.0.1 (Initial Alpha) (unreleased): _ user-1: Don't forget to do this task! Unassigned: No open issues.
How about a HTML report?
$ ditz html
Local generated URL: file:///Users/karl/Code/arabella/html/index.html
$ open html/index.htmlOr you can view Ditz’s project status itself for a fuller report!
Anyway, back to your newly created issue tracking. With everything set up, let’s share it with our team! We’ll first modify our Git repository accordingly.
$ git status
# On branch newUI # Untracked files: # (use "git add <file>..." to include in what will be committed) # # .ditz-config # html/ # issues/
We’ll add our issues to the repository, along with our .ditz-config file as a sample.
$ git add issues/ $ cp .ditz-config .ditz-config.example $ git add .ditz-config.example
We’ll ignore our real .ditz-config file, as well as our html output directory.
$ echo ".ditz-config" >> .gitignore $ echo "html/*" >> .gitignore $ git add .gitignore
$ git status
# On branch newUI # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # new file: .ditz-config.example # modified: .gitignore # new file: issues/issue-f87a61786e74f311d8653f03ecb9091ff8cf96b7.yaml # new file: issues/project.yaml
All sorted - send it off.
$ git commit -m "Set up Ditz (copy and edit .ditz-config.example to your own set up)." $ git push
Et voila - you’re good to go. The basics at least. What next though?
Well, all the other commands are here:
$ ditz helpDitz commands: add: Add an issue add-component: Add a component add-reference: Add a reference to an issue add-release: Add a release archive: Archive a release assign: Assign an issue to a release changelog: Generate a changelog for a release close: Close an issue comment: Comment on an issue drop: Drop an issue edit: Edit an issue grep: Show issues matching a string or regular expression help: List all registered commands html: Generate html status pages init: Initialize the issue database for a new project log: Show recent activity reconfigure: Rerun configuration script release: Release a release releases: Show releases set-component: Set an issue's component shortlog: Show recent activity (short form) show: Describe a single issue start: Start work on an issue status: Show project status stop: Stop work on an issue todo: Generate todo list unassign: Unassign an issue from any releases validate: Validate project status Use 'ditz help <command>' for details.
…*you can set up hooks…
…or write a plugin.
Tags: ditz, issue tracking, walkthrough