In review of #200, Bowei Du (@bowei) suggested keeping the glossary at a high level and locating detailed definitions as close to the code as possible:
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.
The glossary is being slimmed accordingly. Some of the removed detail is worth capturing in docstrings so it has a durable home:
- Actor lifecycle states: document the
SUSPENDED → RESUMING → RUNNING → SUSPENDING → SUSPENDED transitions on the status enum / state type itself.
- Control service RPCs: the semantics of
CreateActor, ResumeActor, SuspendActor, and DeleteActor belong in the proto/service definitions.
- ateom workload RPCs:
RunWorkload, CheckpointWorkload, RestoreWorkload, and the atelet↔ateom contract (gRPC over unix socket) belong on the ateom service definition.
- runsc invocation details: how the sandbox is created/started/checkpointed/restored, and the per-
ActorTemplate binary pinning (URL + SHA-256), belong with the code that drives runsc.
The goal is a single source of truth per definition: the glossary gives a one-to-three-sentence summary of each Substrate-specific term, while anything mechanical lives in a docstring where it gets updated alongside the code it describes.
In review of #200, Bowei Du (@bowei) suggested keeping the glossary at a high level and locating detailed definitions as close to the code as possible:
The glossary is being slimmed accordingly. Some of the removed detail is worth capturing in docstrings so it has a durable home:
SUSPENDED→RESUMING→RUNNING→SUSPENDING→SUSPENDEDtransitions on the status enum / state type itself.CreateActor,ResumeActor,SuspendActor, andDeleteActorbelong in the proto/service definitions.RunWorkload,CheckpointWorkload,RestoreWorkload, and the atelet↔ateom contract (gRPC over unix socket) belong on the ateom service definition.ActorTemplatebinary pinning (URL + SHA-256), belong with the code that drivesrunsc.The goal is a single source of truth per definition: the glossary gives a one-to-three-sentence summary of each Substrate-specific term, while anything mechanical lives in a docstring where it gets updated alongside the code it describes.