This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 70c182f43cd029d056eb930631d2198e2ce3df95 Author: Stephen Mallette <[email protected]> AuthorDate: Fri Oct 9 13:10:52 2026 -0400 Attach record beads to their root as parent-child children Assisted-by: Claude Code:claude-opus-5-5 --- .beads/PRIME.md | 16 +++++++++++----- docs/src/dev/developer/for-committers.asciidoc | 5 +++-- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/.beads/PRIME.md b/.beads/PRIME.md index 43d443d578..9c4acca371 100644 --- a/.beads/PRIME.md +++ b/.beads/PRIME.md @@ -236,9 +236,9 @@ Pinning is what makes a bead permanent — every destructive operation keys on ``` root (feature/epic/task) - ├─relates-to──▶ record TINKERPOP-3456 - ├─relates-to──▶ record apache/tinkerpop#2891 - ├─relates-to──▶ record apache/tinkerpop@374b0c76d0 (written at merge) + ├─parent-child─▶ record TINKERPOP-3456 + ├─parent-child─▶ record apache/tinkerpop#2891 + ├─parent-child─▶ record apache/tinkerpop@374b0c76d0 (written at merge) ├─parent-child─▶ decision "chose X" {rejected: false} │ └─related─▶ decision "Y" {rejected: true} ├─parent-child─▶ task A "implement X" ──caused-by──▶ decision "chose X" @@ -253,8 +253,14 @@ a list, and `bd ready` cannot tell you anything useful about it. see section 7. - **`record` beads** hold external artifacts — JIRA, PR, dev@ thread, proposal, and the commits a landing merged as. The ticket, URL or `owner/repo@sha` goes in `--external-ref`, - which identifies the kind as well. Attach them to the **root**, not to every bead. Create - them pinned. Search first — duplicates are the risk. + which identifies the kind as well, and only a record carries one. Create each as a child of + the **root** (`--parent <root>`), not of any other bead, and pin it. `bin/beads-commits.py` + finds a root's JIRA and PR records among its children, so a record attached any other way + is invisible to `--suggest`. +- **Search first — duplicates are the risk.** `bd search <ref> --status all` matches + external refs; `bd query` has no field for them. When a second root needs an artifact that + already has a record, add `bd dep add <root> <record> -t related` rather than a duplicate. + `--suggest` on that root will not see it, so supply those commits by hand at merge. - Records are the only link between beads and code; commit messages carry no bead ID. The commit record written at merge (section 4) is what makes that link work in reverse — `bd query 'notes="<sha>"' --all` returns the record and its `parent`, for any commit in the diff --git a/docs/src/dev/developer/for-committers.asciidoc b/docs/src/dev/developer/for-committers.asciidoc index a311f2a886..a56b5040f3 100644 --- a/docs/src/dev/developer/for-committers.asciidoc +++ b/docs/src/dev/developer/for-committers.asciidoc @@ -190,7 +190,7 @@ deliverable, and everything belonging to that effort hangs beneath it: [source,text] ---- root (feature/epic/task) - ├─relates-to──▶ record TINKERPOP-3456 + ├─parent-child─▶ record TINKERPOP-3456 ├─parent-child─▶ decision "chose X" {rejected: false} │ └─related─▶ decision "Y" {rejected: true} ├─parent-child─▶ task A "implement X" ──caused-by──▶ decision "chose X" @@ -201,7 +201,8 @@ root (feature/epic/task) Four kinds of bead appear in that graph. A `task` is a unit of work. A `decision` is a choice and carries its reasoning. A `record` points at an external artifact such as a JIRA issue, a pull request, or the commits that a landing merged as, and is the only link between a bead and -the code, because commit messages carry no bead identifiers. The root itself is usually a task or an epic. +the code, because commit messages carry no bead identifiers. A record is a child of the root it +belongs to, and only a record carries an external reference. The root itself is usually a task or an epic. The edges carry as much meaning as the beads. A `parent-child` edge establishes membership in the effort, while a `blocks` edge establishes order, so a subtree without any `blocks` edges is
