issue-states -- manage the states of issues

This repository houses the specification of "issue states" as well as a reference implementation of a library providing an associates data model and resolution logic.

An issue state is a named transient property depending on an issue's metadata. E.g., rather than a property which is actively controlled by an issue tracker's admin or user, it is a property which is determined from the issue's metadata.

An issue's state is selected out of a set of issue states, which may either be hard-coded in an application (discouraged) or specified by some configuration. For a given issue, each of those states is either enabled or disabled based on a "condition" attached to the state. Additionally, a state may or may not be related to other issues within the set.

For a given issue, a resolver may select at most one of the states enabled for the issue.

Example

The example below illustrates a possible set of issue states. In this specific example, ech state overrides the previous one. However, more complex constallations are possible. The states "acknowledged", "assigned" and "resolved" each depend on some piece of metadata being present (or set) for an issue. For example, an issue with an assignee is in the state "assigned" unless it is resolved.

- new
- name: acknowledged
  conditions: acknowledged
  overrides: new
- name: assigned
  conditions: assignee
  overrides: acknowledged
- name: resolved
  conditions: resolution
  overrides: assigned

Motivation

In issue- and bugtrackers, issues are usually assigned a status of some sort, e.g. "open" or "closed". Some issue tracker feature a more rich set of states as well as (sometimes customizable) workflows: a set of possible states and transitions specified by the admin or project maintainer.

Workflows are, essentially, specialized state machines and libraries exist for implementing workflow behavior. However, those are often targeted at a specific environment (e.g. a specific CMS) and generally do not provide any specification format for state machines. Rather, workflows are constructed (more or less) programatically through source code. Persisting, if supported at all, usually only targets databases --using custom database schemas.

We primarily require a specification format for issue-related workflows. As no widely used format appears to exist, we design our own. We will also develop a library for parsing the format and implementing the workflow's behavior.