legume

Source code repository

Legume is a distributed issue tracker, and can be used along side other, more formal, issue trackers as an intra-developer tracking mechanism. I also tend to use it, rather than a web-based ticket tracker, on small, single-file scripts.

Legume leverages the developer tradition of using code comments to make notes about things that need to be addressed. Notes of this sort retain locality; they are reminders for code browsers, and contain meta-data about where to start looking when addressing an issue. They integrate naturally with whatever VCS the developer is using, and make it easy for a developer to remember to remove the comment when the topic is addressed. They require no extra external database.

Legume is developer oriented. Submit issues with the end-user Legume tracker.

Features

The biggest selling feature of legume is that issues are embedded in code. This has a number of benefits:

  • Issues can be place-marks for where developers think things are happening.
  • Commenting code with TODO and FIXME comments is a decades-old traditional developer habit
  • Integrated with version control at an intuitive level, reducing cognitive load. No external integration with VCS necessary.
  • No external DB for tickets. TODOs and FIXMEs are still relevant even if you stop using legume. Which also means…
  • legume is not strictly necessary for working with issues. It’s a convenience tool. This means you don’t have to build your workflow around legume, and nobody in your team needs to install legume. You can find and grep your way through issues.

Legume will also address other, non-developer, use cases by recognizing a todo.txt file in the directory of execution. Legume will assume every line is a separate TODO. This allows easy integration with todo.txt, but also provides a place for sticking issues that either aren’t linked to source, or come from a source other than a developer (e.g., web app). todo.txt syntax is also supported in comments.

  • (A) priorities
  • 2017-03-20 “created” dates
  • due:2017-03-20 “tagged” dates
  • *@contexts_
  • +projects
  • key:value tags
  • Multi-line issues (new issue, blank line, or non-comment breaks issue) tickets. No attachments, no cross-references or dependencies, no robust commenting; history tracking limited to what’s available in the VCS.
  • Efficiency. In a pure state, collating tickets requires walking directory trees and parsing source files. This is addressed by caching, but caches introduce opportunities for sync errors; it’s a necessary wart on an otherwise elegant and simple solution.