docs: supersedes is a replacement link, not a version chain (#6212)
* docs: supersedes is a replacement link, not a version chain Reword the DepSupersedes comment (internal/types/types.go), the `bd supersede` help text, and the graph-links doc: `supersedes` marks an old issue as replaced by a different issue. It is not a version relation and does not imply a version chain. The behavior is unchanged. Promised on #5898 (Q8, quad341 revision 4): a replacement link, not a version-chain link. docs/CLI_REFERENCE.md is pinned to v1.2.2 and picks this up at the next release bump (generate-cli-docs.sh --check passes). Wyvern bead wy-h4xd6f. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PvjeDsoyDfjptvjKZWzcqA * docs: finish the supersedes rewording pass in graph-links + dependencies Maintainer review fixup for PR #6212. The PR's new assertion "This is a replacement link, not a version relation" left the rest of graph-links.md still telling the version-chain story, so the page contradicted itself. Each residual line is byte-identical to base, but the contradiction is new with this commit. Extends the same wording pass to the sites that actually assert version semantics: - frontmatter description: "supersedes chains" -> "supersedes (replacement) links" (this is the rendered page description) - the example comment "# View shows the chain" -> "# View shows the replacement" - "### Version History" -> "### Replacement History" and "# bd-rfc3 is now the current version" -> "# bd-rfc3 is now the live issue" - Best Practice 4 "Document supersedes chains - Note why version changed" -> "Document replacements - Note why the issue was replaced" The use-case list ("Design document versions", "Artifact versioning", "RFC chains") and "Track document evolution" are deliberately left alone: chained replacements legitimately model document evolution without the link itself being a version relation. Also rewords the sibling core-concepts table, docs/core-concepts/ dependencies.md:56, from "Replaced by a newer issue" to "Replaced by a different issue" so both hand-written pages frame the edge the same way. No in-repo reference targets the renamed #version-history anchor. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
This commit is contained in:
parent
6ee989342a
commit
83184f4c6a
4 changed files with 11 additions and 11 deletions
|
|
@ -28,8 +28,8 @@ Examples:
|
|||
var supersedeCmd = &cobra.Command{
|
||||
Use: "supersede <id> --with <new>",
|
||||
GroupID: "deps",
|
||||
Short: "Mark an issue as superseded by a newer one",
|
||||
Long: `Mark an issue as superseded by a newer version.
|
||||
Short: "Mark an issue as superseded by a replacement issue",
|
||||
Long: `Mark an issue as superseded by a different (replacement) issue.
|
||||
|
||||
The superseded issue is automatically closed with a reference to the replacement.
|
||||
Useful for design docs, specs, and evolving artifacts.
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ Dependencies have a type that determines whether they block work.
|
|||
| `discovered-from` | Found during work on another issue |
|
||||
| `caused-by` | Root cause link |
|
||||
| `validates` | Test or verification link |
|
||||
| `supersedes` | Replaced by a newer issue (`bd supersede old --with new`) |
|
||||
| `supersedes` | Replaced by a different issue (`bd supersede old --with new`) |
|
||||
|
||||
Specify with `--type`:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: Graph Links in Beads
|
||||
description: "Non-blocking links between issues: replies-to threads, relates-to, duplicates, and supersedes chains"
|
||||
description: "Non-blocking links between issues: replies-to threads, relates-to, duplicates, and supersedes (replacement) links"
|
||||
---
|
||||
|
||||
Beads supports several types of links between issues to create a knowledge graph. These links enable rich querying and traversal beyond simple blocking dependencies.
|
||||
|
|
@ -114,9 +114,9 @@ bd show bd-bug2
|
|||
- Original (canonical) issue remains open
|
||||
- `duplicate_of` field stores the canonical ID
|
||||
|
||||
### supersedes - Version Chains
|
||||
### supersedes - Replacement Links
|
||||
|
||||
Marks an issue as superseded by a newer version. The old issue is automatically closed.
|
||||
Marks an issue as superseded by a different (replacement) issue. The old issue is automatically closed. This is a replacement link, not a version relation: the new issue takes the old one's place.
|
||||
|
||||
**Created by:**
|
||||
- `bd supersede <old-id> --with <new-id>`
|
||||
|
|
@ -142,7 +142,7 @@ bd create --title "Design Doc v2" --type task
|
|||
bd supersede bd-doc1 --with bd-doc2
|
||||
# Result: bd-doc1 closed with superseded_by: bd-doc2
|
||||
|
||||
# View shows the chain
|
||||
# View shows the replacement
|
||||
bd show bd-doc1
|
||||
# Status: closed
|
||||
# Superseded by: bd-doc2
|
||||
|
|
@ -247,14 +247,14 @@ bd duplicate bd-bug42 --of bd-bug17
|
|||
bd duplicate bd-bug58 --of bd-bug17
|
||||
```
|
||||
|
||||
### Version History
|
||||
### Replacement History
|
||||
|
||||
Track document evolution:
|
||||
|
||||
```bash
|
||||
bd supersede bd-rfc1 --with bd-rfc2
|
||||
bd supersede bd-rfc2 --with bd-rfc3
|
||||
# bd-rfc3 is now the current version
|
||||
# bd-rfc3 is now the live issue
|
||||
```
|
||||
|
||||
### Message Threading
|
||||
|
|
@ -272,7 +272,7 @@ Build conversation chains (via orchestrator mail):
|
|||
1. **Use relates-to sparingly** - Too many links become noise
|
||||
2. **Prefer specific link types** - `duplicates` is clearer than generic relates-to
|
||||
3. **Keep threads shallow** - Deep reply chains are hard to follow
|
||||
4. **Document supersedes chains** - Note why version changed
|
||||
4. **Document replacements** - Note why the issue was replaced
|
||||
5. **Query before creating duplicates** - `bd search` first
|
||||
|
||||
## See Also
|
||||
|
|
|
|||
|
|
@ -1224,7 +1224,7 @@ const (
|
|||
DepRepliesTo DependencyType = "replies-to" // Conversation threading
|
||||
DepRelatesTo DependencyType = "relates-to" // Loose knowledge graph edges
|
||||
DepDuplicates DependencyType = "duplicates" // Deduplication link
|
||||
DepSupersedes DependencyType = "supersedes" // Version chain link
|
||||
DepSupersedes DependencyType = "supersedes" // Replacement link: old issue superseded by a different issue (bd supersede); not a version relation
|
||||
|
||||
// Entity types (HOP foundation - Decision 004)
|
||||
DepAuthoredBy DependencyType = "authored-by" // Creator relationship
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue