issuegraph

A spec for issue dependencies

Issuegraph defines seven optional fields you add to the top of an issue as YAML frontmatter. The fields record how issues depend on each other. Any tracker can store them, and any tool can read them to work out which issues are ready to start.

blocked-by serialize-with

YAML frontmatter

---
issuegraph:
  blocked-by: ["#231", "#234"]
  decomposed-from: "#230"
  serialize-with: "#232"
  priority: 1

---

Fields

blocked-bylist of refsMust close before this issue can start.
serialize-withrefNot worked at the same time. Either can go first.
together-withrefWorked together with this issue as one unit.
duplicate-ofrefThe original. Readers ignore the duplicate.
decomposed-fromrefThe issue this was split from. No effect on order.
priorityinteger, 0–3 · default 20 is most urgent.
evidence"asserted" | "verified"Whether the writer checked the issue’s claims.

ref is an issue ID as your tracker writes it: 231, "#231", ABC-231, or owner/repo#231. All fields are optional.

Reading the graph

Ready

An issue is ready when everything it’s blocked by is closed and nothing it’s serialized with is in progress.

Effective priority

An issue takes the highest priority of anything waiting on it, so a P3 that blocks a P0 is treated as P0.

Parallel work

Ready issues with no dependency path between them can be worked at the same time.

Build with issuegraph

Try the CLI with no install. This reads the block at the top of an issue body and prints what it declares:

printf -- '---\nissuegraph:\n  blocked-by: ["#231"]\n  priority: 1\n---\nShip the parser.\n' \
  | npx -y @issuegraph/cli parse
@issuegraph/cliRead, order and edit Issuegraph blocks from the command line.npm install -g @issuegraph/cli
@issuegraph/readerRead the block out of an issue body and work out the graph: ready set, effective priority, cycles.npm install @issuegraph/reader
@issuegraph/writerWrite the block into an issue body, or change one field without touching the rest.npm install @issuegraph/writer
@issuegraph/deriveTurn a set of issues into the order to work them in, with the reason each held issue waits.npm install @issuegraph/derive
@issuegraph/coreThe field names, defaults and allowed values every other package shares.npm install @issuegraph/core
@issuegraph/storeA browser-side store for a graph you edit, plus the port your tracker plugs into.npm install @issuegraph/store
@issuegraph/viewerDraw a graph as a work order, themeable with CSS.npm install @issuegraph/viewer
@issuegraph/editorEdit controls drawn on top of the viewer, saved through the store.npm install @issuegraph/editor

Every package is TypeScript, Apache-2.0, and runs on Node 18 or later. None of them fetches anything or needs a credential.

Issuegraph describes the work, not how it gets done. Assignees, status, and progress stay in your tracker.