docs: one name per domain, and it is the URL's - #242
Merged
Merged
Conversation
The provider directory, the agent processor, the URL segment and the SDK service disagree about what a domain is called, in four different ways, and nothing said which one was right. osapi-io/osapi#566 has the map. The URL decides, because it is the one of those a consumer depends on and the only one that cannot be changed without a major version. The name is the concept rather than the tool: a container domain is container with a Docker implementation inside it, the way the NTP domain is ntp with a chrony implementation inside it. Two shapes stay allowed because they are real rather than accidental. A provider may serve several URL segments when it gathers facts that are separate resources, which is what host does for hostname, os and uptime. A segment may be served by several providers when they implement one concept, which is what network is. 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! 😊🕹️ |
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.
Settles osapi-io/osapi#566. One section in
domains.md.The provider directory, the agent processor, the URL segment and the SDK service disagree about what a domain is called, in four different ways, and nothing said which one was right.
The rule
A domain carries one name across every layer, and the URL decides what it is. The URL is the one a consumer depends on and the only one that cannot be changed without a major version, so everything else moves to it.
The name is the concept, never the tool. A container domain is
containerwith a Docker implementation inside it, the way the NTP domain is alreadyntpwith a chrony implementation inside it. Naming the directorydockeris a claim that stops being true the day a second runtime is supported.Abbreviations are not names either:
memory, notmem.Two exceptions, because they are real
A provider may serve several URL segments when it gathers facts that are genuinely separate resources.
hostanswershostname,osanduptime, and collapsing those into one endpoint would be worse.A segment may be served by several providers when they implement one concept.
networkis interfaces, routes and reachability.What this means in practice
node/aptnode/packagenode/memnode/memorycontainer/dockercontainer/with a docker implementationscheduled/cronschedule/with a cron implementationcronscheduledockercontainerhostandnetworkstay as they are, under the two exceptions.Why the rule lands before the rename
The rename is mechanical once the rule exists, and large. Writing it down first means new domains inherit it rather than copying whichever neighbour they happened to read, and it means the rename is a change that makes the code match a stated rule rather than one that argues for a preference in a diff.
It also unblocks the per-domain pages in this repo, which were waiting on knowing what to call them.
just testpasses.🤖 Generated with Claude Code
https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c