docs: acknowledge issues as a first-class entity
commit
b3e4396docs: acknowledge issues as a first-class entity
The spec abstract and README promise an issue tracker; the docs never mentioned one. Issues join the granularity examples and derived list in abstractions.adoc and get a FAQ section: the plainest typed-tree instance, where assignees/labels/states are struct fields.
Reviews
No reviews of this commit yet — record a verdict below.
Start a review
docs/abstractions.adoc
@@ -18,7 +18,7 @@
* *Authorization* — refname-keyed rules gate who may advance the ref.
* *History* — the ref's commit history is the audit trail.
-*Granularity rule:* one ref per independently-authored entity (`refs/meta/member/*`, `refs/meta/comments/*`, `refs/meta/effects/*`, `refs/meta/results/*`); one ref for repo-global state (`refs/meta/account`, `refs/meta/config`).
+*Granularity rule:* one ref per independently-authored entity (`refs/meta/member/*`, `refs/meta/issues/*`, `refs/meta/comments/*`, `refs/meta/effects/*`, `refs/meta/results/*`); one ref for repo-global state (`refs/meta/account`, `refs/meta/config`).
Entities that different actors write concurrently must not share a ref.
Writes stay conflict-free; reads aggregate refs into views.
@@ -244,7 +244,8 @@
* *Toolchains* — typed trees under `refs/meta/toolchains/*`; a resource effects declare, not a trigger.
The repo carries its own execution environment with provenance, as ~1KB hash-pinned manifests; only the sandbox touches the bytes.
They keep a subcommand only because import/activation logic is nontrivial; if that shrinks, the subcommand dies.
-* *Members, accounts, comments* — typed trees behind meta-refs (1+2), written as signed commits (4), admitted by the gate (5).
+* *Members, accounts, issues, comments* — typed trees behind meta-refs (1+2), written as signed commits (4), admitted by the gate (5).
+Issues are the plainest instance of all: assignees, labels, and states are struct fields, so multiple assignees or custom states are schema, not platform features.
* *Fanout indexes* — discovery without ref enumeration: `refs/meta/index/*` maps object oids to the entities anchored to them, rebuilt by an effect (6) and written via the worker's signed commit (4).
Clients read the index; a stale or absent index degrades to scanning ref tips, never to wrong answers.
* *Redaction* — the deliberate exception to retention: an object-level yank, scoped to content reachable only from `refs/meta/*`.
docs/faq.adoc
@@ -46,6 +46,16 @@
'''''
+== Issues
+
+*I want an issue tracker.*
+An issue is a typed tree on its own ref under `refs/meta/issues/*` — written, gated, synced, and audited exactly like a comment.
+
+*I want multiple assignees, custom states, or fields no forge offers.*
+Assignees, labels, and states are struct fields, and the struct is the schema; extending the issue model is a typed-tree change, not a platform request.
+
+'''''
+
== Comments and anchors
*I want to leave a comment on specific lines of code.*