docs: how a provider's error reads - #245
Merged
Merged
Conversation
A provider's error reaches a job result, the audit log and a CLI user's screen, so its wording is an interface. Nothing said what shape it takes and the tree grew four. Settles it as <domain> <verb>: what went wrong, which sysctl and netplan already use and which sorts and greps usefully. Names the two habits already in the tree and why each is wrong. An error that announces it failed says nothing the wrapping did not, because these are almost always wrapped. An error naming the command rather than the operation leaks the implementation into a message a user reads, and stops being true when the implementation changes. The four sentinels stay exactly as they are. They are compared with errors.Is rather than read, so the convention does not apply to them. Refs osapi-io/osapi#565 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c
|
Thank you for contributing to this project! 😊🕹️ |
retr0h
added a commit
to osapi-io/osapi
that referenced
this pull request
Oct 2, 2026
Applies osapi-io/specs#245 to the file provider, which carried the worst of the four shapes. Every error here began "failed to", which is the one Go's own guidance argues against: these are almost always wrapped, so the reader saw "deploy schedule entry: failed to execute template: ..." where the words carried nothing the context had not. They now read "file deploy: ...", "file template: ...", "file status: ..." and "file undeploy: ...", named for the operation rather than for the fact that something went wrong. Two things the tests caught. The ownership error spans two lines, so a regex anchored on fmt.Errorf missed it. And the template failures are wrapped by deploy rather than raised by template, so the assertion naming the originating operation was wrong until it was read off the actual error. Five providers still carry the older shapes. This is the first. Refs #565 Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
retr0h
added a commit
to osapi-io/osapi
that referenced
this pull request
Oct 2, 2026
Three more providers onto <domain> <verb>, following osapi-io/specs#245. schedule used <verb> <domain> and named cron, which the rename had already taken out of every other layer: "create cron entry" becomes "schedule create", "invalid cron entry name" becomes "schedule: name must not be empty". ntp used a bare <domain>, so five different operations all reported "ntp:" and the reader could not tell a failed write from a failed chronyc call. Each now names its operation. certificate used <verb> <domain>, the mirror of the convention. Each has an exact-match and a %q variant of its name validation, and the %q one is easy to miss because the exact-match string reads like the whole rule. certificate's was, until the tests caught it. Two providers left: service uses a bare <domain> and user has "chpasswd failed", which names a command rather than an operation. Refs #565 Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
One section in
providers.md, one routing row in the skill. Settles osapi-io/osapi#565 so the mechanical fix has something to follow.A provider's error reaches a job result, the audit log and a CLI user's screen. Nothing said what shape it takes, and the tree grew four:
The shape
<domain> <verb>: what went wrongsysctl and netplan already use it. It sorts and greps usefully, and reads the same whether the error arrives alone or wrapped three deep.
The two habits, and why each is wrong
An error does not announce that it failed. These are almost always wrapped, so
failed to execute templaterenders as "deploy schedule entry: failed to execute template: ...". The words carry nothing the context did not already.An error names the operation, not the command.
chpasswd failedleaks the implementation into a message a CLI user reads, and stops being true the day the implementation changes.user set passwordsurvives that.Not in scope
The four sentinels stay exactly as they are. They are compared with
errors.Israther than read, so the convention does not apply:%wwrapping on any path carrying a cause stays mandatory, since an error that loses its cause cannot be matched, which is what the sentinels are for.just testpasses. All skill links and anchors resolve.🤖 Generated with Claude Code
https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c