Skip to content

Documentation

Ids

The id grammar, why you write them by hand, and why they are never reused.

An id is a family, a dash, and then levels that alternate between numbers and letters: SEND-1, SEND-1.a, SEND-1.a.1, SEND-1.a.1.b.

The grammar

  • The family is uppercase letters, digits and underscores, starting with a letter: SEND, TWO_FACTOR, CHECKOUT. It picks the file. SEND-1 lives in hi/send.md.
  • Levels alternate strictly. The first level is a number, the next a letter, the next a number, and so on. SEND-1.a.2.c is well formed; SEND-1.2 is not.
  • Numbers are steps, letters are cases. Reading an id tells you what kind of thing it is before you read the sentence.
  • No padding. SEND-01 is refused, because SEND-01 and SEND-1 would be two names for one thing.

Why you write them by hand

A generated id is a position. A hand-written id is a name, and a name is something you can say out loud in a meeting, put in a commit message, or paste into a ticket. You are the one who has to use it, so you are the one who picks it.

A brand new id just works. An id that already exists is refused, with the file, the line, and the next free id in the message:

sh 
$ hi CHECKOUT-1 "something else"
error: CHECKOUT-1 already exists in hi/checkout.md:14
hint:  next free is CHECKOUT-2

Nothing is written to disk when hi refuses, for any reason. Validation happens before any write, so a refusal never leaves half a change behind.

Permanent, and never reused

The whole point of an id is that it can be quoted somewhere hi will never see: a ticket, a spec, a commit, a conversation. An id that can be reassigned is worse than no id, because the quotation silently starts pointing at something else.

So hi never renumbers anything, and retiring never frees an id. hi retire moves a criterion and every case beneath it into ## Retired, and capture, hi issue and hi check all treat a retired id as taken forever.

hi cannot stop you renumbering a file by hand, so permanence is a convention the tool supports rather than one it enforces. What it can do is refuse to be the one that breaks it.

Cases go with their parent

A case is written directly under the criterion it is a case of, in the file where that parent actually lives, not at the bottom of whatever file the family was declared in. Hanging a case off something that does not exist is refused, and so is hanging one off something retired: the parent was withdrawn, and a new case under it would be intent nobody agreed to.

Next

The CLI reference covers all eight verbs.