docs: add a glossary of core terms#200
Conversation
Julian Gutierrez Oschmann (juli4n)
added
the
kind/docs
| For deeper detail, see the [Architecture](architecture.md) and | ||
| [API Guide](api-guide.md). | ||
|
|
||
| ## How the pieces fit together |
There was a problem hiding this comment.
Bit of a nit, but my expectation for a glossary would be just a list of terms and their definitions. The addition of the sequence diagram and resource model feels like they belong somewhere else.
This is mostly from the standpoint of discoverability when people are making modifications to the system as it's not immediately obvious that there will be diagrams in the glossary to change.
Suggest finding a different home for the diagrams?
There was a problem hiding this comment.
Agreed. Pulled the diagrams out in 4dce2ee so the glossary is just terms now. I'll relocate them to the architecture docs in a follow-up rather than dropping them.
| These are not Kubernetes objects; they live in the control-plane database | ||
| (Valkey/Redis) because they change too frequently for etcd. | ||
|
|
||
| - **Actor**: a single instance derived from an `ActorTemplate`, identified by a |
There was a problem hiding this comment.
We should be careful about where we are defining things. For a glossary, I would expect it to remain at a high level vs referencing things like enum states etc as this will be hard to maintain consistency across the entire codebase. In addition, having multiple sources of definitions may confuse the agent coding depending on which source they end up referencing.
Can we keep the glossary definitions to be summaries at the high level? More low level descriptions should be kept as close to the code definitions as possible (i.e. in docstrings) so there are less consistency issues.
This comment applies in general to the other entries...
There was a problem hiding this comment.
Makes sense. Cut the state sequence and RPC/enum detail throughout, leaving short summaries. Filed #236 to move that detail into docstrings near the code. Applied your "in general" note to the other entries too.
| DNS-1123 actor ID. It is the unit that is suspended and resumed, and it moves | ||
| between workers over its lifetime. An Actor record tracks status | ||
| (`SUSPENDED` → `RESUMING` → `RUNNING` → `SUSPENDING` → `SUSPENDED`) and its | ||
| snapshot references. (Some older internal docs call this a "session".) |
There was a problem hiding this comment.
We should try to avoid reference older internal docs, at least not yet before our first real release!
There was a problem hiding this comment.
Removed. The "session" mention (and the older-docs reference) is gone from the intro entirely.
|
|
||
| ## Runtime concepts | ||
|
|
||
| - **gVisor**: the sandboxing technology Substrate uses to isolate and snapshot |
There was a problem hiding this comment.
No clear we need to define this?
| - **kubectl-ate**: a `kubectl` plugin CLI for managing the Actor lifecycle | ||
| (create, resume, suspend, delete, logs) and listing Workers. | ||
|
|
||
| ## Runtime concepts |
There was a problem hiding this comment.
I don't know if these terms need a special definition...
We should focus the glossary on terms that are unique to Substrate and will need clarification for people external to the project.
There was a problem hiding this comment.
Agreed on both. Cut gVisor, runsc, and "pause container" since they're external tech, not Substrate vocabulary. The one relevant fact, that suspend/resume builds on gVisor's checkpoint/restore, is now folded into the Suspend/Resume definitions.
Frederick F. Kautz IV (fkautz)
force-pushed
the
docs/glossary
branch
from
9567ff1 to
66f8fe2
Compare
Address review feedback on agent-substrate#200: - move the sequence/class/state diagrams out of the glossary (they belong with the architecture docs, where people look for diagrams to update) - keep definitions to high-level summaries; drop low-level RPC names and enum states that should live in docstrings near the code - remove references to older internal docs - cut generic runtime terms (gVisor, runsc, pause container) that are not unique to Substrate
Adds docs/glossary.md defining the terms used across the project (resources, control-plane records, components, runtime/sandbox concepts, snapshots, and networking) plus three UML diagrams showing how they relate: a sequence diagram (activation flow), a class diagram (resource model), and a state-machine diagram (actor lifecycle). Links it from the README documentation section. Scoped to documenting the names as they exist in the codebase; rename proposals are left to a separate discussion (agent-substrate#131). Addresses agent-substrate#131
Address review feedback on agent-substrate#200: - move the sequence/class/state diagrams out of the glossary (they belong with the architecture docs, where people look for diagrams to update) - keep definitions to high-level summaries; drop low-level RPC names and enum states that should live in docstrings near the code - remove references to older internal docs - cut generic runtime terms (gVisor, runsc, pause container) that are not unique to Substrate
Frederick F. Kautz IV (fkautz)
force-pushed
the
docs/glossary
branch
from
66f8fe2 to
4dce2ee
Compare
3 participants
Addresses #131
Adds
docs/glossary.md: a single place that defines the terms used acrossAgent Substrate and shows how they relate.
What it covers
components (ate-api-server, atecontroller, atelet, ateom, atenet,
podcertcontroller, kubectl-ate), runtime/sandbox concepts (gVisor, runsc,
pause container, checkpoint/restore), snapshots (golden, last, storage), and
the Uniform DNS Mesh.
diagram (resource/ownership model, grouped into Kubernetes-object and
control-plane-record packages), and a state-machine diagram (actor lifecycle).
Scope
Per the issue thread, this documents the names as they exist in the codebase;
rename proposals are intentionally left to a separate discussion, so this PR is
documentation-only (not a renaming proposal).
Accuracy
Every term and diagram was checked against the code and existing docs. Project
terminology and casing are reused where things are already named (for example
"Uniform DNS Mesh", the atelet "Herder", and the "interior gVisor" coordinator),
and component responsibilities, RPC names, relationships, and the actor status
lifecycle map to their sources.