docs(engdocs): re-review ERROR_HANDLING.md against cmd/bd and refresh its marker (#7267)
The Last reviewed marker (2026-07-07) passed the 90-day limit in
scripts/check-doc-freshness.sh at 2026-10-06 00:00 UTC, so the required
"Check doc flags freshness" job fails on every PR and merge-group run
(#7266).
Re-reviewed against cmd/bd at e72cd8b31 and corrected what had drifted:
- createConfigYaml takes three arguments.
- cmd/bd/sync.go has no warning or ignored-error sites any more; its
citations are gone. Line-number citations into init.go and create.go
no longer matched and are replaced by search strings.
- internal/syncbranch was removed with the sync-branch pipeline; the
syncbranch.Set example and the sync.branch bullet are gone.
- No code writes last_import_hash; the tracking-metadata examples now
show the bd_version write (SetLocalMetadata) and verifyMetadata as
init.go has them.
- CheckReadonly also exits ExitMigrationFrozen under a migration freeze.
- HandleProxyCapabilityError is added to the helper list.
Fixes #7266
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
parent
c33d30aa10
commit
800d43eb8d
1 changed files with 25 additions and 31 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Error Handling Guidelines
|
||||
|
||||
Last reviewed: 2026-07-07
|
||||
Last reviewed: 2026-10-05
|
||||
|
||||
Freshness source: `cmd/bd/*.go`, especially command error exits and JSON error
|
||||
helpers in `cmd/bd/errors.go`.
|
||||
|
|
@ -47,7 +47,8 @@ every `defer`), and `main()` maps the sentinel to exit code 1.
|
|||
|
||||
**Narrow exceptions still using `os.Exit`:** process-level gates that run before
|
||||
or outside the `RunE` error path — e.g. `CheckReadonly`, which aborts a blocked
|
||||
command after flushing metrics first. A handful of pre-existing direct
|
||||
command after flushing metrics first (exit 1 in read-only mode,
|
||||
`ExitMigrationFrozen` under a migration freeze). A handful of pre-existing direct
|
||||
`os.Exit(1)` calls also remain inside handler bodies; new command code should
|
||||
return a `HandleError*` value instead of adding more.
|
||||
|
||||
|
|
@ -67,7 +68,7 @@ return a `HandleError*` value instead of adding more.
|
|||
|
||||
**Example:**
|
||||
```go
|
||||
if err := createConfigYaml(beadsDir, false); err != nil {
|
||||
if err := createConfigYaml(beadsDir, false, ""); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to create config.yaml: %v\n", err)
|
||||
// Non-fatal - continue anyway
|
||||
}
|
||||
|
|
@ -80,10 +81,9 @@ if err := createConfigYaml(beadsDir, false); err != nil {
|
|||
- Core functionality still works
|
||||
|
||||
**Files using this pattern:**
|
||||
- `cmd/bd/init.go` (lines 155-157, 161-163, 167-169, 188-190, 236-238, 272-274, etc.)
|
||||
- `cmd/bd/sync.go` (lines 156, 257, 281, 329, 335, 720-722, 740, 743, 752, 762)
|
||||
- `cmd/bd/create.go` (lines 333-334, 340-341)
|
||||
- `cmd/bd/sync.go` *(handles Dolt sync operations)*
|
||||
- `cmd/bd/init.go` — search for `"Warning: failed` (config.yaml, `.gitignore`,
|
||||
git exclude, and tracking-metadata writes)
|
||||
- `cmd/bd/create.go`, `cmd/bd/gc.go` — search for `WarnError(`
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -107,9 +107,7 @@ _ = os.Remove(tempPath)
|
|||
- Primary error already reported
|
||||
|
||||
**Files using this pattern:**
|
||||
- `cmd/bd/init.go` (line 209, 326-327)
|
||||
- `cmd/bd/sync.go` (lines 696-698)
|
||||
- `cmd/bd/sync.go` *(sync cleanup)*
|
||||
- `cmd/bd/init.go` — search for `_ = store.Close()`
|
||||
- Dozens of other locations throughout the codebase
|
||||
|
||||
---
|
||||
|
|
@ -166,7 +164,7 @@ if err != nil {
|
|||
### Creating Auxiliary Config Files → Pattern B (Warn)
|
||||
|
||||
```go
|
||||
if err := createConfigYaml(localBeadsDir, false); err != nil {
|
||||
if err := createConfigYaml(localBeadsDir, false, ""); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to create config.yaml: %v\n", err)
|
||||
// Non-fatal - continue anyway
|
||||
}
|
||||
|
|
@ -186,8 +184,8 @@ defer func() {
|
|||
### Optional Metadata Updates → Pattern B (Warn)
|
||||
|
||||
```go
|
||||
if err := store.SetMetadata(ctx, "last_import_hash", currentHash); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to update last_import_hash: %v\n", err)
|
||||
if err := store.SetLocalMetadata(ctx, "bd_version", Version); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to write bd_version local metadata: %v\n", err)
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -205,7 +203,7 @@ if err := store.CreateIssue(ctx, issue, actor); err != nil {
|
|||
|
||||
```go
|
||||
// BAD: Same type of operation handled differently
|
||||
if err := createConfigYaml(dir, false); err != nil {
|
||||
if err := createConfigYaml(dir, false, ""); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: %v\n", err) // Warns
|
||||
}
|
||||
if err := createReadme(dir); err != nil {
|
||||
|
|
@ -216,7 +214,7 @@ if err := createReadme(dir); err != nil {
|
|||
|
||||
```go
|
||||
// GOOD: Consistent pattern for similar operations
|
||||
if err := createConfigYaml(dir, false); err != nil {
|
||||
if err := createConfigYaml(dir, false, ""); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to create config.yaml: %v\n", err)
|
||||
}
|
||||
if err := createReadme(dir); err != nil {
|
||||
|
|
@ -285,15 +283,10 @@ defer store.Close()
|
|||
if err := store.SetConfig(ctx, "issue_prefix", prefix); err != nil {
|
||||
return HandleError("failed to set issue prefix: %v", err)
|
||||
}
|
||||
|
||||
if err := syncbranch.Set(ctx, store, branch); err != nil {
|
||||
return HandleError("failed to set sync branch: %v", err)
|
||||
}
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
- `issue_prefix` - Defines how all issue IDs are generated
|
||||
- `sync.branch` - Critical for git synchronization workflow
|
||||
|
||||
**Rationale:** These settings are prerequisites for basic operation. Without them, the system cannot function correctly. A failure here indicates a serious problem (e.g., filesystem issues, database corruption).
|
||||
|
||||
|
|
@ -303,28 +296,25 @@ Tracking metadata **enhances functionality** but the system works without it:
|
|||
|
||||
```go
|
||||
// Pattern B: Warn and continue
|
||||
if err := store.SetMetadata(ctx, "bd_version", Version); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to store version metadata: %v\n", err)
|
||||
// bd_version is clone-local state, so it goes through SetLocalMetadata.
|
||||
if err := store.SetLocalMetadata(ctx, "bd_version", Version); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to write bd_version local metadata: %v\n", err)
|
||||
// Non-fatal - continue anyway
|
||||
}
|
||||
|
||||
if err := store.SetMetadata(ctx, "repo_id", repoID); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to set repo_id: %v\n", err)
|
||||
}
|
||||
|
||||
if err := store.SetMetadata(ctx, "last_import_hash", hash); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to update last_import_hash: %v\n", err)
|
||||
// verifyMetadata writes the field, reads it back, and warns on failure.
|
||||
if verifyMetadata(ctx, store, "repo_id", repoID) && !quiet {
|
||||
fmt.Printf(" Repository ID: %s\n", repoID[:8])
|
||||
}
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
- `bd_version` - Enables version mismatch warnings on upgrades
|
||||
- `repo_id` / `clone_id` - Helps with collision detection across clones
|
||||
- `last_import_hash` - Optimizes staleness detection (falls back to mtime if unavailable)
|
||||
|
||||
**Rationale:** System degrades gracefully if tracking metadata is unavailable. Core functionality (creating issues, importing data) still works. Failures here might indicate temporary issues (e.g., read-only filesystem) that shouldn't block the entire operation.
|
||||
|
||||
**See also:** `cmd/bd/init.go` lines 206-272 for detailed inline documentation of this distinction.
|
||||
**See also:** the `CONFIGURATION METADATA` and `TRACKING METADATA` comment blocks in `cmd/bd/init.go` for inline documentation of this distinction.
|
||||
|
||||
### File Permission Errors
|
||||
|
||||
|
|
@ -378,6 +368,11 @@ func HandleErrorWithHintRespectJSON(message, hint string) error
|
|||
// Exit 1 with no message, when the error was already reported
|
||||
func SilentExit() error
|
||||
|
||||
// Proxied-server capability refusals: a nil error passes through as nil, a
|
||||
// *ProxyCapabilityError is rendered (JSON-aware) with its own exit code, and
|
||||
// any other error falls back to HandleErrorRespectJSON
|
||||
func HandleProxyCapabilityError(err error) error
|
||||
|
||||
// Pattern B — prints "Warning: ..." to stderr and returns nothing
|
||||
func WarnError(format string, args ...interface{})
|
||||
```
|
||||
|
|
@ -393,4 +388,3 @@ func WarnError(format string, args ...interface{})
|
|||
- `cmd/bd/errors.go` - The `HandleError*` / `WarnError` / `SilentExit` helpers and the `exitError` sentinel that `main()` maps to an exit code
|
||||
- `cmd/bd/defer.go` - Clean example of Pattern A: `return HandleError(...)` from a `RunE` with `SilenceUsage`/`SilenceErrors` set
|
||||
- `cmd/bd/init.go` - Examples of all three patterns
|
||||
- `cmd/bd/sync.go` - Examples of Pattern B for metadata operations and Pattern C for cleanup operations
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue