Contributing¶

Guidelines for contributing to nim-typestates.

Development Setup¶

# Clone the repository
git clone https://github.com/elijahr/nim-typestates.git
cd nim-typestates

# Install dependencies
nimble install -d

# Build the CLI
nimble build

# Run tests
nimble test

Running Tests¶

# Run all tests
nimble test

# Run specific test file
nim c -r tests/tbasic.nim

Documentation¶

Local Preview¶

# Install Python dependencies
pip install -r docs-requirements.txt

# Serve docs locally
mkdocs serve

Auto-Generated Diagrams¶

The diagrams in this documentation are automatically generated from source code snippets. This ensures they stay in sync with the actual typestate definitions.

Generating Diagrams¶

# Generate all diagrams from examples/snippets/
nimble generateDocs

# Or manually:
python3 scripts/generate_diagrams.py

This reads *_typestate.nim files from examples/snippets/ and generates SVG diagrams in docs/assets/images/generated/.

Creating New Diagram Sources¶

To add a new auto-generated diagram:

Create a snippet in examples/snippets/yourname_typestate.nim:

import ../../src/typestates

type
  YourType = object
  StateA = distinct YourType
  StateB = distinct YourType

typestate YourType:
  states StateA, StateB
  transitions:
    StateA -> StateB

Run nimble generateDocs to regenerate all diagrams.
Reference the generated image in docs: ![YourType](assets/images/generated/yourtype.svg)

Code Style¶

Follow standard Nim style conventions
Use nimble format if available
Keep lines under 100 characters where practical

Pull Requests¶

Fork the repository
Create a feature branch
Make your changes
Run tests: nimble test
Submit a pull request

Reporting Issues¶

Please include:

Nim version (nim --version)
nim-typestates version
Minimal reproduction case
Expected vs actual behavior