Prototype of a distributed bug tracking system backed by git.
Bugs, or issues, are stored together with a program’s source code in an in-tree branch called issues in human-readable format; indexed and searchable through git-issues. Conflict resolution favours a “both sides win” strategy to minimise impact of mid-air collisions.
git-issue sets out to innovate on the traditional client-server relationship that has served bug tracking well over the last two decades. Instead of using a create-read-update-delete database that require data locks to prevent data races, it aims to employ conflict resolution through three-way merges, meaning each developer has immediate offline access to the entire bug database.
By providing the repository and issue reports together under distributed version control, git-issue facilitates tighter integration of code and issues.
As is the case with changes in a git repository, git-issue provides a staging area that is an intermediary area where issues can be formatted, changed, and reviewed before “committing” them. This means you can operate on multiple issue reports concurrently.
When viewing—or showing—an issue, they are annotated with commit messages they are referenced in. This allows you to track changes related to an issue directly from the comfort of a git client. git-issue comes coupled with a built-in web server serving a traditional bug tracking user interface for easier tracking and overview. This lets you navigate source code changes and jump between changes related to issues.
Issues have the following metadata associated with them:
- SHA-1
- The unique descriptor of this issue. Notably, git-issues does not use bug numbers, but a unique SHA-1 value. This value is referred to throughout as an issue.
- Title
- Short description of the issue.
- Description
- Summary of the issue, reproduction steps, affected systems, &c.
- Labels
- Free-text labels.
- Assignee
- Email of the person assigned to the issue.
To file a new issue, you may edit one of the predefined templates in your favourite editor:
% git issue add
Most metadata fields can be prepopulated with flags, much like git-send-email:
% git issue add --label foo --label bar
Displaying an issue works much like showing a normal git object through git-show:
% git issue show ISSUE
Where ISSUE is the SHA-1 of the issue you want to show.
You can output the issue in different formats:
% git issue show ISSUE --format json
To interact with, search, and show issues in a web browser you can serve the built-in HTTPD in a local port on your system:
% git issue serve
Serving on http://localhost:6666/
Or on a custom port:
# git issue serve example.com:80
Serving on https://example.com:80
As issues are distributed flat files conflict resolution is important.
Comments to issues are by definition never conflicting unless two remotes have edited the same public comment and not synchronised in between. In the happy path scenario where comments are write-only, additional comments will append by merge timestamp rather than be considered as mid-air collisions as they are in certain other bug tracking software.
Resolution of conflicts in the updating of
issue descriptions, titles, assignee,
and so forth is more challenging,
and will need to be manually resolved by the user.
Labels could be treated a a special case
where additions and removals are discounted,
and only changes to existing phrases or words
could be considered conflicting
(think git diff -p word-diff or word-by-word diffs).