Contribution Guide¶
Contributor policy and working conventions for StoryTangl maintainers.
- Coding Style & Architecture (semantic)
- 0) North star
- 1) Layering & dependencies
- 2) Packages & modules
- 3) Class design
- 4) Data model & serialization
- 4a) Type purity on attributes
- 5) Mutations & replay
- 6) Handlers & dispatch
- 7) Naming & API surface
- 8) Extensibility & hooks
- 9) Errors & invariants
- 10) Determinism & RNG
- 11) Performance posture
- 12) Observability
- 13) Tests (contracts > mechanics)
- 14) Anti-patterns
- 15) Dereferencing & Resolution Patterns
- Related Guides
- Docstring & Autodoc Conventions
- Goals
- A. Class docstrings: “Why / Key Features / API (+ optional Notes / See also)”
- B. Subpackage
__init__.pydocstring: “Conceptual layers + Design intent” - C. Module-level docstrings
- D. Member docstrings (methods/attributes)
- E. Cross-references & Sphinx roles (do this, not that)
- F. Autodoc RST “summary pages” (per subpackage)
- G. Pydantic & signatures (house policy)
- H. Naming, terms, and tone
- I. Documenting Dereferencing & Iterator Patterns
- J. Documenting Iterator Semantics
- K. Documenting
is_dirtyand Audit Flags - L. Examples & admonitions
- M. Privacy & surface curation
- N. Checklists (for PRs)
- O. Sphinx config nudges
- P. Quick examples from our codebase (as reference)
- Q. Related Guides
- Exception Policy
- Custom World Runtime Hooks