contributor_recipes

Contributor Recipes

Use these recipes to scope common changes. They are starting points, not permission to edit every listed file.

Add A New Runtime Primitive

Start with the public surface in include/tsm/runtime and expose only the aliases that belong in include/tin/runtime.h.

Checklist:

• define capacity, overflow, ownership, and stepping behavior;
• add direct runtime integration tests for success and full-storage cases;
• add resource accounting if the primitive owns storage;
• update docs/runtime.md or a focused package guide;
• run the focused runtime test and the full CTest gate.

Add A New Actor Composition Feature

Start with include/tsm/runtime/actor.h.

Checklist:

• keep ports typed and non-owning;
• keep actor group ordering deterministic;
• test link movement, empty/pending behavior, and drain behavior;
• update docs/actors.md or docs/actor_tutorial.md;
• add or update an example only after primitive behavior is tested.

Add A New Coroutine Wait Pattern

Start with include/tsm/runtime/coroutine.h and executor behavior in include/tsm/runtime/executor.h.

Checklist:

• define what resumes the task;
• define cancellation behavior;
• account for task frames, waiters, and timer slots;
• add tests for ready, waiting, cancelled, and repeated-use cases;
• update docs/coroutines.md.

Add A New Platform Profile

Start with include/tsm/platform/profile.h and the target-facing header under include/tsm.

Checklist:

• name compiler and runtime assumptions explicitly;
• keep vendor APIs in adapters or examples;
• add a compile smoke test for the platform API surface;
• add a target-shaped example when users need to see integration shape;
• update docs/thal.md.

Add Or Change Machine Authoring Semantics

Start with include/tsm.h and include/tsm/core_algorithms.h.

Checklist:

• write a small machine that demonstrates the semantic rule;
• add authoring and runtime behavior tests;
• update generated trace or evidence when semantics affect verification;
• update docs/tsm.md and related authoring docs;
• mention migration impact when existing machines may change behavior.

Add Or Change YAML/JSON Tooling

Start with tools/tsm_tool.py, spec/ir, and tooling tests.

Checklist:

• update schema or parser validation;
• add import/export tests for the accepted shape;
• update generated artifact smoke tests;
• update docs/tooling.md, docs/machine_ir_json.md, or docs/generation_pipeline.md;
• keep comments and user-facing diagnostics clear enough for hand-authored files.

Add A New Example

Start by deciding what the example proves that existing examples do not.

Checklist:

• keep the example focused on one integration story;
• make it build through CMake;
• add a CTest entry when it can run on the host;
• add --manifest support when resource accounting is part of the story;
• document how to build and what output means;
• avoid using an example as the only test for primitive behavior.

Add A Public Facade Or Package Surface

Start with the smallest public include or package target that users need.

Checklist:

• update facade headers under include/tin, include/tio.h, include/thal.h, or include/tin.h;
• update CMake export or pkg-config metadata when target names change;
• add a package consumer compile test;
• update docs/tin.md and docs/public_api_boundary.md;
• preserve existing include paths unless intentionally deprecating them.