Contributing

Thank you for your interest in contributing to Minions!

Getting Started

1. Fork the repository on GitHub
2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/minions.git

3. Install dependencies:

   pnpm install

4. Create a feature branch:

   git checkout -b feature/my-feature

Development Commands

TypeScript

# Build all packages
pnpm run build

# Run tests
pnpm run test

# Type check / lint
pnpm run lint

Python

# Install the Python SDK in development mode
cd packages/python
pip install -e ".[test]"

# Run Python tests
pytest -v

# Run a single test file
pytest tests/test_validation.py -v

Project Structure

Directory	Description
packages/core/	TypeScript SDK (minions-sdk on npm)
packages/python/	Python SDK (minions-sdk on PyPI)
packages/cli/	CLI tool
apps/docs/	Astro Starlight documentation site
apps/web/	Marketing / playground web app
spec/	Specification documents
examples/	Usage examples

Pull Request Process

1. Ensure your code passes pnpm run lint and pnpm run test
2. For Python changes, ensure pytest -v passes in packages/python/
3. Update documentation if your changes affect the public API
4. Add tests for new functionality
5. Keep PRs focused — one feature or fix per PR

Code Style

• TypeScript strict mode for all TS packages
• Python 3.11+ with type annotations for the Python SDK
• ESM modules ("type": "module")
• JSDoc/docstrings on all public exports
• No runtime dependencies in either SDK

Spec Changes

Changes to the specification (spec/) require discussion in a GitHub issue first. The spec is versioned — breaking changes go into a new spec version.

License

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