decentralised issue tracking with lentil

Upon releasing lentil I received a message on the feasability of using it as a distributed issue tracker. I had some thoughts on the idea, the occasion was right to put them on paper.

In my opinion an issue tracker serves three basic purposes:

• internal use: or to remind the developer(s) what is broken, what area needs more love, what there is to be done
• task management: to triage, label and assign tasks related to the issues; especially important in companies or big organisations/projects
• external use: to allow users to communicate their experience to developers (bug reports, issue requests, etc.)

These purposes are (of course) not mutually exclusive! Let’s analyse them and see how lentil would work in the wild.

Internal use

The most basic one, needed by every project. If you are given a codebase to maintain, the immediate needs would be to check whether it compiles and see what there is to do. lentil does the job well: the ability to add tags to an issue means that, later on, you can list issues, filter them for severity/type/file, etc., so you can have a clear view of where you stand. Every output is exportable to file, so third parties casually checking the repo don’t even need the software themselves; just run lentil . --output outstanding-bugs.txt and point it to them.

There is also a crude (but useful) report to see the the “most popular tags” in the codebase and even if you need more control over how you want to display the data, exporting is one -f csv away.

Task management

Task management means addressing the life of an issue related to actions of an individual or a team (Rick should fix this, Sally triage that, etc.); it is preferred, especially in corporate environment, that the process is logged somehow.

lentil can achieve this with the flexibility of tags. Every step can be labelled ([assigned:Rick], [review:Sally]); also recall that search expression like -t (tag) accept a REGEX, which can go a long way in reporting who has to do what or the future workflow.

A distributed Version Control System is of course very helpful to document and reconstruct the developing work, but not necessary. As an exmple, I put a [bug] tag in every issues which was reported to me as a bug, and subsequently [fixed] upon patching it and [closed] when I receive a positive final feedback by the user (I often migrate them do a different file at this point); it allows me to filter out non opened reports (-T (fixed|closed)) and still having them documented when needed.

External use

This is the tough one, how can users interact with lentil as an issue tracker? Do they need particular expertise? Is that even feasible?

The amount of trouble a user should undergo to report an issue or a feature request should be minimal: in the end they are helping you and communicating with them makes you gather precious information (sometimes even beyond the bug at hand). Making the user register to a site is a burden (and most often a no-no decentralisation-wise), having the user learn a new interface (or a DVCS) is even more of an effort.

So, is there a decentralised tool which can be used to gather inputs from users? Yes, there is, the electronic mail, and more specifically mailing lists:

• mailing lists are accessible to the user: all you need is, well, an email address! The interface (for writing a message, reading messages) is well known and we can assume basic proficiency from pretty much anyone. Are you sure your audience has a twitter account? Or want to register for one? With email, these problems are solved. By decreasing the friction to type in a reply/read a message for the user, we are increasing the chance of feedback.
• mailing lists are easy for the developers: as 2015 I run this site off shared hosting (some 20€/year); even this cheap solution has a one-click mailing list setup! Mailing lists are soo much more easy to maintain that, say, a forum and can be configured in a few clicks; you can even have your message archive www-accessible/searchable if you so wish.

The usual objection is that this paradigm is well suited only for small-to-medium projects, but let’s look around: two of the most important and complex open-source projects, the Linux kernel and Git, use mailing lists to receive bug reports. This answer from Kernel developer Greg Kroah-Hartman is an eye opener on mailing lists and how well they scale (where other fancy solutions fail).

How would lentil integrate with this? Upon receiving the mail, developers should insert a TODO near the relevant portion of the code (or in a issue.txt file if the source of the problem is unclear), with a reference to the originating message if necessary. This approach takes less than a minute and invites immediate triaging, a definite plus for every issue database.

Conclusion

The workflow of issue tracking can decentralised and lentil has the capability of achieving this, collaborating with other commonly used tools. The proposed solution is just an example: lentil is unix philosophy compliant (does one thing, tries to do it well, uses text streams as I/O), so other mix-and-matches could be assembled around it.