Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
233 lines (171 loc) · 6.51 KB

CONTRIBUTING.md

File metadata and controls

233 lines (171 loc) · 6.51 KB

Contributing to SpacetimeDB Workflow Engine

Development Setup

This project uses mise to manage development tools and run tasks. Mise ensures everyone uses the same tool versions and provides a consistent development experience.

Prerequisites

  • mise - Development tool manager (required)
  • SpacetimeDB CLI - For running integration tests

Installing mise

# Install mise
curl https://mise.run | sh

# Add to your shell (choose one):
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc   # Bash
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc     # Zsh
echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish  # Fish

# Restart your shell or run:
source ~/.bashrc  # or ~/.zshrc

Getting Started

# Clone the repository
git clone https://github.com/perplexes/spacetime-workflow-engine
cd spacetime-workflow-engine

# Trust the mise configuration (required once per project)
mise trust

# Install all development tools (Rust, Node.js)
mise install

# Run setup to install dependencies and verify environment
mise run setup

This will:

  • Install Rust stable (for building the workflow engine)
  • Install Node.js 22 (for TypeScript integration tests)
  • Install npm dependencies for TypeScript tests
  • Verify SpacetimeDB CLI is available

SpacetimeDB Setup

# Install SpacetimeDB CLI (if not already installed)
mise run setup-spacetime

# Start local SpacetimeDB server
spacetime start

# Deploy the example module
mise run publish

# Verify it's working
mise run logs

What mise Manages

The mise.toml file defines:

  • Tool versions: Rust 1.75, Node.js 22
  • Environment variables: SpacetimeDB connection settings
  • Tasks: Build, test, lint, deploy commands

When you enter the project directory, mise automatically:

  • Activates the correct tool versions
  • Sets up environment variables
  • Makes all tasks available via mise run <task>

Running Tests

Unit Tests

mise run test              # All unit tests
mise run test-core         # Core library only
mise run test-specific -- test_name  # Specific test
mise run tv                # With verbose output

Integration Tests

Integration tests require a running SpacetimeDB server.

# Start SpacetimeDB if not running
spacetime start

# Full integration suite (deploys module + runs TypeScript tests)
mise run integration

# Or run TypeScript tests only (assumes module already deployed)
mise run test-ts

All Available Test Commands

mise run test          # Rust unit tests
mise run test-core     # Core library tests only
mise run test-ts       # TypeScript integration tests
mise run integration   # Full suite (deploy + TypeScript)
mise run tv            # Verbose test output
mise run verify        # fmt + clippy + test

Code Style

Formatting

Code must pass formatting and linting checks:

mise run fmt       # Format code
mise run clippy    # Run lints
mise run verify    # Run all checks (fmt + clippy + test)

Conventions

  • Use snake_case for timer and signal wire names (the derive macros do this automatically)
  • Workflow handlers should be stateless structs - all state goes in State type
  • Prefer the fluent API: WorkflowResult::to("step").after_timer(T::X, 1.secs())
  • Use #[derive(Timer)] and #[derive(Signal)] for type safety
  • Keep workflow logic in handler methods; reducers should be thin wrappers

Documentation

  • Public items should have doc comments
  • Examples in doc comments should use ignore since they require SpacetimeDB context
  • Update relevant docs in docs/ when changing public APIs

Project Structure

spacetime-workflow-engine/
├── core/               # workflow-core crate (pure Rust, no SpacetimeDB deps)
│   └── src/
│       ├── handler.rs  # WorkflowHandler trait
│       ├── types.rs    # WorkflowResult, TimerRequest, etc.
│       ├── registry.rs # Global workflow registry
│       └── traits.rs   # Timer, Signal traits
├── macros/             # workflow-macros crate (proc macros)
│   └── src/
│       └── lib.rs      # Timer, Signal derives + install! macro
├── example/            # Example SpacetimeDB module
│   └── src/
│       ├── lib.rs      # Module entry point
│       └── workflows/  # Example workflow implementations
├── tests/
│   └── typescript/     # TypeScript integration tests
└── docs/               # Documentation

Making Changes

Adding a New Feature to Core

  1. Add implementation to appropriate file in core/src/
  2. Export from core/src/lib.rs if public
  3. Add to core/src/prelude.rs if commonly used
  4. Write unit tests in the same file or core/src/proptest_tests.rs
  5. Update docs/API.md if it's a public API

Adding a New Derive Macro

  1. Add implementation in macros/src/lib.rs
  2. Add tests in example/ showing usage
  3. Update docs/API.md with examples

Adding an Example Workflow

  1. Create new file in example/src/workflows/
  2. Export from example/src/workflows/mod.rs
  3. Register in install!{} block in example/src/lib.rs
  4. Add test reducers if needed
  5. Add TypeScript tests in tests/typescript/integration.test.ts
  6. Regenerate bindings: spacetime generate --lang typescript --out-dir tests/typescript/bindings --project-path example

Commit Messages

Follow conventional commit style:

Add feature X for Y

- Bullet points for details if needed
- Keep lines under 72 characters

Co-Authored-By: Your Name <email@example.com>

Good commit message examples from this repo:

  • Add TypeScript integration tests and fix module reload
  • Restructure as workspace for easy Cargo integration
  • Add ergonomic API: derive macros, fluent builder, duration extensions

Pull Request Process

  1. Create a feature branch from main
  2. Make your changes with tests
  3. Run the full verification: 
    mise run verify      # fmt + clippy + test
mise run integration # if you changed runtime behavior
  4. Update documentation as needed
  5. Submit PR with clear description of changes

Testing Checklist

Before submitting:

  • mise run fmt-check passes
  • mise run clippy passes
  • mise run test passes
  • mise run integration passes (if runtime behavior changed)
  • New public APIs are documented
  • Examples compile and work

Getting Help

  • Check existing documentation
  • Look at example workflows in example/src/workflows/
  • Open an issue for questions or bugs