darcsforge.orkin – Issue Tracker

Platforms: Django

Darcsforge’s default Issue Tracker is meant to be extremely simple. Through simplicity it is meant to act as a configurable exemplar of more project-specific Issue Trackers or as a starter environment on route to larger, more robust dedicated systems such as Bugzilla or Roundup.

Issues are meant to be editable within the Django admin interface. This leads to an unfortunate double-usage of fields: Reporter and Description reflect the current comment/update, even if they show the original values on the edit form.

Future

Eventually it should be expected that a rewrite to address Django “nfa” (newforms-admin) will correct this.

Repository-Based Issue Tracking

Distributed source control can imply complex issue states. Tools for simple, “stupid” repository-based issue tracking have been built. Another tool for issue tracking via distributed source control is Ditz and it may be a useful reference point to the simpler “lossy” model used by this issue tracker.

Philosophy of Darcsforge’s repository-based issue tracking:

  • A repository-based issue is a part of a project’s documentation and is an ordinary text file. Only a very small subset of the data should be used algorithmically and it should be skimmed via simple, stupid RegEx patterns, with a certain “fail-safeness” for data it does not parse.
  • The canonical version of the issue should be the file in the repository. The file can be referred to directly and thus there is no use in verbatim copying of the file into a database.
  • The canonical change log of the issue should be the patch history. When updating the current state of the issue in the database it shouldn’t be necessary to replicate the entire change history of the issue, the patch history should speak for itself.
  • The database state is primarily a nicety for searching and status display.
  • reStructuredText is the expected format, but not the required one. Database updates are done via simple, configurable RegEx scraping rather than format parsing.

The provided tools are directly accessibly through the python manage.py orkin command interface. Tools provided:

–issue

Format an issue to standard output (reStructuredText)

This outputs a simple text file that may be used as-is by the pull tool following future edits, or may serve as the basis for a hand-modified issue state.

–pull

Grabs available changes from issues in the repository and copies them to the database

The Pull tool is built of two sub-tools: the Hunter and Puller that both follow very simple heuristics to determine the state of issues in the repository that should have updates.

Issue Hunter

The Hunter seeks through the current manifest of repository-controlled files looking for a RegEx pattern. The default pattern follows the following simple hierarchy: an issues directory at the top level or just below a docs directory at the top level. (Neither final s is required in the directory names.) Within this issues directory files may be placed as slug.rst. When two slugs conflict they can be placed into a date directory hierarchy similar to that used by the default URL patterns: year/mon/day/. The full date should not be necessary if it is unambiguous (for example if test-issue was used in two different years you need only make a folder for each year).

Hunter then attempts to match the paths that it finds with existing issues in the database by matching the date provided by any applicable date directories to an issue’s posted date and then matching the slug of the filename and the slug of the issue. Hunter prints a warning and skips an issue path that is ambiguous in the database (ie, a slug without enough disambiguating date directories).

Change Puller

The change puller looks only at the current state of the repository (doing a darcs annotate on the Hunter-found files) and searches the file lines for a specific RegEx pattern of field updates. The default pattern is based upon reStructuredText Field Lists, for the appropriate fields the puller searches for:

:Field Name: Value

It only matches in the case that the opening : is in the first column of the line and it only captures the value until the end of its first line (multi-line reST values are therefore truncated, but ). Everything else in the document is ignored, so the document may be used for comments, status updates, logs, code, free-form poetry or whatever makes sense for the project.