Skip to content

Contributing

Jump to bottom
Roberto Cruz edited this page May 15, 2026 · 2 revisions

Contributing

Thank you for contributing to TietAI Synthea! This guide covers the workflow for bug fixes, new features, and new disease modules.

Getting Started

# Fork the repo on GitHub, then clone your fork
git clone https://github.com/<your-username>/tietai-synthea.git
cd tietai-synthea

# Set up development environment
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Install pre-commit hooks
uv run pre-commit install

Development Workflow

# Create a feature branch
git checkout -b feat/my-feature

# Make changes, then run tests
uv run pytest

# Check formatting
uv run black --check src/ tests/
uv run flake8 src/

# Type checking
uv run mypy src/

# Auto-format
uv run black src/ tests/

Adding a Disease Module

  1. Create a JSON state machine in resources/modules/my_condition.json
  2. Validate: uv run python -m synthea.validate_module resources/modules/my_condition.json
  3. Generate a test population: uv run synthea -p 100 -m my_condition -s 42
  4. Visualise: uv run synthea --graphviz my_condition && dot -Tpng my_condition.dot -o my_condition.png
  5. Add a test in tests/ that generates patients and asserts the condition appears in health records

Refer to the Disease Modules page for the full JSON schema reference.

Pull Request Checklist

  • Tests added / updated and passing (uv run pytest)
  • Code formatted (uv run black src/ tests/)
  • No new linting errors (uv run flake8 src/)
  • Type hints correct (uv run mypy src/)
  • Module validated if applicable
  • PR description explains the motivation and what changed

Reporting Bugs

Open an issue at GitHub Issues with:

  • Synthea version (uv run synthea --version)
  • Python version (python --version)
  • OS and architecture
  • Command or code that reproduces the bug
  • Expected vs. actual behaviour
  • Debug output if available (--log-level debug)

Requesting Features

Open a GitHub Discussion in the Ideas category before opening a PR for large changes. This avoids duplicate effort and ensures alignment.

Code Style

  • Formatter: Black (line length 100)
  • Linter: flake8
  • Type hints: required for all public functions
  • Docstrings: one-line summary only for simple functions; longer description only when the behaviour is non-obvious
  • Comments: only when the why is non-obvious

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

Clone this wiki locally