Distributed/offline issue tracking

Csaba Hoch Distributed/offline issue tracking [discussion, reviewed] <hh/298> (2009-05-20) Children: hh/1076, hh/1230

== Motivation ==

It would be nice to use an issue tracking system that lets us work
offline as git does.

I don't have to talk about the merits of distributed (and offline) issue
tracking. But I have to mention its disadvantages:
- It will be harder for the users to send bugs. On the other hand, I
  think most users want to send bugs on the mailing list anyway,
  because they are not sure if it is indeed a bug.
- The issue tracker is updated only when we push. I don't think that's
  an important problem though.

== Articles on the subject ==

I have found various resources that talk about DITs (Distributed Issue
Trackers).

Offline Issue Tracking [1]:

    A blog entry. The author mentions TicGit, Git-issues and Ditz.

Distributed bug tracking [2]:

    An article from May 2008. The author mentions Bugs Everywhere,
    ticgit, Scmbug, DisTract, DITrack, and Ditz.

A lists of distributed issue trackers [3]:

    A plain list with a few notes. Mentions 13 DITS.

Distributed bug tracking [4]:

    An article from April 2008. The author mentions Fossil, Bugs
    Everywhere, DITrack, DisTract, TicGit and Ditz.

Ditz versus Bugs Everywhere [5]

    Comparison of Ditz and Bugs Everywhere. Interesting article.

== Features ==

Important features:
- Generating HTML pages from the issue database, so that we can push
  it to our homepage (it shows the users where are we heading, and it
  also shows the maturity of the project).
- Issues should have tags, just like posts on the heap. This would
  replace the current hierarchy of the Todo file.

Nice-to-have features:
- Easily readable and editable issue database. E.g. Ditz stores every
  issue in a YAML file.

== Concrete tools ==

=== Feasible options ===

All tools that are in this category support git. They either support
git explicitly or are VCS agnostic. All of them have clean command
line interfaces. None of them has a comprehensive documentation; at
most they have a good tutorial.

Note: sometimes one item is both under "Pros" and "Misc". The reason
is I wanted the language, repository and database format to be in the
Misc section; but I also wanted to show which ones are pros.

==== Bugs Everywhere (git, bazaar, mercurial, rcs, arch) ====

Homepage:
    http://bugseverywhere.org/be/show/HomePage

Pros:
    - Used to be the leading project in this niche.
    - Written in Python.

Cons:
    - "perhaps abandonware, last commit was July 2007" -- [4] (in April 2008)
    - "The Ditz mailing list is really active with people debating
      ideas for new features. The be mailing list is now showing some
      signs of life after looking dead in August." [5] (in Dec 2008)

Misc:
    - Written in Python.
    - The project uses Bazaar.

==== TicGit ====

Homepage with tutorial screenshots:
    http://wiki.github.com/schacon/ticgit

Pros:
    - Seems easy to use and has a nice tutorial.
    - Issues may have tags.
    - Hosted by GitHub.

Cons:
    - Git-Issues a "better version" of TicGit.
    - The tool was implemented between March and May of 2008; it isn't
      very active now.

Misc:
    - Written in Ruby.
    - Hosted by GitHub.
    - I haven't managed to find out how the issue database is stored.

=== Git-Issues ===

Homepage with examples:
    http://github.com/jwiegley/git-issues/tree/master

Pros:
    - "It replicates the functionality of packages like ticgit, but
      does so in the form of a more standalone Python script. You can
      check this script in along with your project in order to ensure
      that all contributors are able to view the bug database using
      the same version of the script that you used to create them".
    - Active project since May 2008. Has a major and quite a few minor
      contributors [6].
    - Issues may have tags.
    - Written in Python.
    - Hosted by GitHub.

Cons:
    - I could not find how to modify a ticket without having to edit
      the XML file that stores it. Even though the homepage states the
      following: "Note that for any XML haters out there, you’ll never
      have to look at this data."

Misc:
    - Written in Python.
    - Hosted by GitHub.
    - The issue database is stored in XML.

==== Ditz ====

Pages:
    - Homepage with screenshots: http://ditz.rubyforge.org/
    - HTML generated from the issue database: http://ditz.rubyforge.org/ditz/
    - Ditz Commander (GUI): http://code.google.com/p/ditz-commander/

Pros:
    - The source code of the Ditz project is stored in git.
    - Can generate HTML page from issues.
    - "The Ditz mailing list is really active with people debating
      ideas for new features." [5]
    - There is a GUI which can be used to browse and edit the tickets.

Misc:
    - Written in Ruby.
    - Hosted by Gitorious.
    - The issue database is stored in YAML.
    - Last commit was in March 2009.

=== Not feasible options ===

They don't support git.

- Fossil -- a version control system with integrated bug tracker
- DITrack -- subversion only
- DisTract -- monotone VCS only

=== Haven't looked at them ===

- Scmbug (glues together VCS and other bug tracking software, such as
  bugzilla)
- bartman's git-case (git)
- Stick (git)
- cil (Command-line issue tracker with some git integration for closing
  bugs on commit)
- dbug

== Conclusion ==

I don't think Bugs Everywhere is the right solution. I think one of
Git-Issues and Ditz will be the winner. Git-issues does not support
HTML generation; Ditz does not support tags. I lean a bit towards
git-issues: maybe we can write a small module that generates web pages
from the XML files that make up the issue database. If only they used
YAML... But we should definitely try out both before we make a
decision.

We should have a look at the other DITs,  but they were mentioned only
on [3] (with the exception of Scmbug), so they are probably even more
immature then the four I talked about.

[1] http://my.opera.com/karmazilla/blog/2009/01/24/offline-issue-tracking
[2] http://lwn.net/Articles/281849/
[3] http://dist-bugs.kitenet.net/software/
[4] http://community.livejournal.com/evan_tech/248736.html
[5] http://blog.tplus1.com/index.php/2008/12/22/ditz-versus-bugs-everywhere/
[6] http://github.com/jwiegley/git-issues/graphs/impact

I made a stackoverflow answer out of this post:
http://stackoverflow.com/questions/2186628/textbased-issue-tracker-todo-list-for-git/2187005#2187005

Now, almost exactly a year later, do you use a distributed issue tracker?

Side question: has Hk's issue_tracker become the tool you had in mind?
If not, what does it lack?

> Now, almost exactly a year later, do you use a distributed issue
> tracker?

I use only Heapkeeper's issue tracker. I haven't tried the ones I
wrote about.

> Side question: has Hk's issue_tracker become the tool you had in
> mind?

Yes.

> If not, what does it lack?

It would be good to add new posts from the web interface.

Also, sometimes the table format where one issue is one row would be
easier to read. It is also good to add information like the
implementors of the issues as a column of this table. I know that you
made steps in this direction and implemented this table; but I haven't
used it yet.

>> If not, what does it lack?
>
> It would be good to add new posts from the web interface.

This applies to all of Hk, of course :)

> Also, sometimes the table format where one issue is one row would be
> easier to read. It is also good to add information like the
> implementors of the issues as a column of this table. I know that you
> made steps in this direction and implemented this table; but I haven't
> used it yet.

Yes, and it is usable and looks good, but I'm hotlinking the icons
from Canonical's Launchpad, which is a bad, bad thing to do. This
should be resolved, e.g. by taking the appropriate icons and gluing
together to form a new icon set, containing only those that we need.
Also, I'm not sure those icons are free to use. (But Launchpad is an
open source project, so we can reasonably expect.)