Documentation

HIVE

Distributed Bug Tracker

Home | Documentation | Code | Issues

01) High-level Issue Representation
02) Command Line Interface
    02.1) Initializing a Hive Database
    02.2) Adding Issues
    02.3) Viewing Issues
    02.4) Editing Issues
    02.5) Committing Changes
    02.6) Managing Labels
03) Web Interface
04) Searching for Issues
05) Data Format Details
    05.1) Labels
    05.2) Targets
    05.3) Issues

1) High-level Issue Representation

All of Hive's data are stored files inside of a directory called .hive-bt in the root of your repository (next to .hg or .git). These files are version-controlled alongside the other files in your repository.

Logically, each issue consists of several pieces of information:

an ID (string, consisting of 64 hex characters)
a title (string)
a body describing the issue (string)
an author (string)
a priority (number, higher->more urgent)
zero or more assignees (strings) representing people who are coordinating the resolution of the issue.
zero or more labels (strings)
zero or more targets (strings) representing, e.g., the version in which the issue should be resolved.
optionally, a reporter (string) if the person submitting the issue is not the one who reported it.
zero or more comments, each of which consists of:
- an author (string)
- a body (string)
- optionally, a parent comment

Using hive probably does not require understanding how these things are actually represented on disk, but if you're interested in that kind of thing, the last section on this page describes the representation in a bit more detail.

2) Command Line Interface

The main means of interacting with issues stored in hive is via the command line interface. Running hive --help will show a list of possible commands, some of which are described below.

2.1) Initializing a Hive Database

You can set up the necessary database structure for hive by running the following command from within a Mercurial or Git repository:

$ hive init

Setting the -c flag will commit the new (empty) structure to the repository. If -c is set, you can specify a commit message with -m MESSAGE; if you don't specify such a message, a default message will be used.

2.2) Adding Issues

You can create a new issue using the new command:

$ hive new

or by its alias, add:

$ hive add

In either case, you will be prompted for a title, and then an editor will open, which you can use to enter the body of the issue. Or, if you provide the --stdin flag, the body will be read from stdin and no editor will be opened. If you want to create an issue with an empty body, you will need to provide the --empty flag.

The new command also takes a large number of optional arguments that can modify the initial state of the issue, including:

-t TITLE or --title TITLE to set the title without an interactive prompt
-l LABEL or --label LABEL to associate a label with the issue. This can be used arbitrarily many times to associated multiple labels, e.g. hive add -l LABEL1 -l LABEL2 ...
-p PRIORITY sets the issue's priority (defaults to 0)
-a NAME or --assignee NAME to assign the issue to someone. Like -l, this can be used arbitrarily many times.
-t TARGET or --target TARGET to set the issue's target

2.3) Viewing Issues

You can view a summary of existing issues with:

$ hive list

or, for short,

$ hive ls

By default, this command displays all issues; but it also accepts search terms as arguments, for viewing a subset of issues (see the section on "Searching for Issues" for more details of the kinds of search terms you can use). Additionally, providing the --all flag or specifying status:any as a search term will include closed issues in the listing.

You can view the details with the show command, which takes an issue ID (or a prefix thereof) as an argument:

$ hive show ID

This will show a summary of the issue, including the full text of its body and comments, if any.

2.4) Editing Issues

Most of the parameters that can be set when creating an issue can also be modified ex post facto using a command:

hive label ISSUE_ID LABEL1 LABEL2 ... adds labels to the issue with the given ID. If the -d flag is provided, this command removes the labels instead of adding them.
hive assign ISSUE_ID NAME1 NAME2 ... adds assignees to the issue. You can use the --me flag to assign yourself instead of giving names. If -d is provided, remove the given assignees instead of adding them.
hive priority ISSUE_ID PRIORITY sets the given issue's priority.
hive target ISSUE_ID TARGET sets the given issue's target.

Issues can be closed by running hive close ISSUE_ID, and closed issues can be reopened with hive open ISSUE_ID.

2.5) Committing Changes

Eventually, after making local changes to your issues, you will want to commit those changes (and, maybe, to push them to a remote server). Since hive stores its issues in regular files, you are welcome to manage this process yourself. However, hive also provides a commit command, which does some additional optimizations before committing.

$ hive commit

You can also provide a custom message with -m MESSAGE; if you don't provide one, a default message will be used.

2.6) Managing Labels

Arbitrary labels can always be assigned to issues, but sometimes it is helpful to change the "look and feel" of a particular label. To this end, the edit-label command can be used to store information about a label, including a description and the colors that should be used when displaying the label.

$ hive edit-label LABEL

This command will prompt for a description, as well as foreground and background colors in HTML hex format.

3) Web Interface

hive also includes a simple web interface for interacting with issues.

As of right now, the web interface is read-only (i.e., it cannot be used to modify issues, only to view them). The plan is for the web interface eventually to include support for editing issues, and also for interaction via the web (so that users can submit issues without requiring a local installation of hive).

You can start a local server to serve the web interface by running hive web from a repository managed with hive. Passing the -b flag to hive web will launch a web browser pointed at the right place; or, you can manually navigate to http://localhost:5000 after starting the server.

If you are planning on using this to host a public-facing issue tracker, you can use NGINX as a reverse proxy. If the root URL of the issue tracker is not /, you can provide a base URL with -u. This should not include a trailing slash. For example, the Hive issue tracker at https://hz.mit.edu/hive/bugs was launched with hive web -u /hive/bugs.

4) Searching for Issues

The default view in the web interface, as well as the usual output of hive ls, is a listing of all open issues. You can narrow the set of issues that are displayed through searching.

In the command line interface, search terms should be given after hive ls, for example hive ls search_term search_term .... In the web interface, they can be typed into the search bar.

In both cases, words separated by spaces are searched for separately, but quotation marks can be used to search for longer terms. For example, searching for laser beam will search for issues that contain both the word "laser" and the word "beam", but searching for "laser beam" will search for issues that contain the phrase "laser beam".

Certain prefixes affect the way a search proceeds. For example:

label:enhancement searches for issues with the "enhancement" label
id:a2e searches for issues whose ID starts with "a2e"
priority:2 searches for issues whose priority is equal to 2
priority>:2 searches for issues with priority greater than 2
priority<:2 searches for issues with priority less than 2
status:open searches for open issues
status:closed searches for closed issues
status:any disregards status
body:text searches for the given text in the issue's body only
title:text searches for the given text in the issue's title only
author:text searches for the given text in the issue's author name only

5) Data Format Details

Generally speaking, it should not be necessary to deal with hive's files directly, but you never know. This section describes the structures hive uses to represent issues and related information. Some of these design choices were inspired by other distributed issue trackers, particularly Bugs Everywhere and git-bug.

This section describes the data format version 1.

All of Hive's data are stored in a directory called .hive-bt in the root of your repository (next to .hg or .git). Inside of this directory, you'll find a file called version containing information about the version of the data format used in that directory. Other information about the issues is stored in a few subdirectories, described below.

5.1) Labels

Information about labels is contained in a directory called labels. Each file in this directory corresponds to a single label. For example, a file called wontfix describes a label called wontfix. Each of these files contains a single JSON object with zero or more of the following keys:

description should map to a string containing a description of the tag. This description cannot contain any formatting; it will be interpreted verbatim as a description.
bgcolor and fgcolor describe the colors that should be used to display the label. If they are not both specified, simple defaults will be used. Both the command-line interface and the web interface will use these colors.

Labels not present in this directory can still be assigned to issues, but the interfaces will assume an empty description and use default colors for issues not described in the labels directory.

Valid label names can contain arbitrary characters, except for colons (:), spaces (), backslashes (\), forward slashes (/), and periods (.), which are not allowed in label names because of the ways labels are represented and used internally. In particular, slashes are disallowed because they are path separators; colons are disallowed because they are not part of valid filenames on Windows; spaces are disallowed because of the way the web interface applies styles to issues; and periods are disallowed as an easy way to prevent the .keep file in the labels directory from being treated as a label.

5.2) Targets

Information about targets is contained in a directory called targets. Each file in this directory corresponds to a target, and contains a single JSON object with zero or more of the following keys:

due_date should map to a string containing a date in YYY-MM-DD format, specifying when the target is due.
description should map to a string containing a description of the target.
active should map to a boolean indicating whether the target is still in progress

As with labels, it is possible to assign issues to targets that are not present in this directory, or to have targets that do not specify all of the above keys. In those cases, default values will be assumed.

Valid target names follow the same rules as valid label names.

5.3) Issues

Information about the issues themselves is stored in a directory called issues. The issues directory will contain multiple subdirectories, one for each issue. Each issue is identified by a 64-character hex sequence; the first 32 characters are a digest of a UUID (version 4), and the last 32 characters are the MD5 hash of the initial parameters.

Each issue's directory contains one or more files, each of which represents a series of one or more changes to the state of that issue. Each of these files' names consists of three fields: a logical timestamp, a UNIX timestamp, and an MD5 hash of the contents. Each file contains a JSON array, containing JSON objects representing each action in the series.

Most commands create files representing a single change to an issue, but these files can later be combined together when committing issues to the repository, in order to minimize the number of extra files hive adds to the repository history.

Storing changes to issues (rather than storing the issue's current state) and using these particular naming conventions affords a large degree of "merge tolerance," in the sense that two people can work on issues separately but still end up with a consistent internal state after a merge, with no manual intervention. Merge conflicts on issues should be exceedingly rare; the hope would be that they can only really occur if multiple people are manually running hive pack separately and committing the results.

Caching

One obvious downside of this representation is that operations on these structures can be slow, since determining the current state of an issue requires looping over all actions associated with the issue. To mitigate this concern, hive caches information about issues and refers to the cache when possible.