Contributing

Help build Orch8

Orch8 is source-available under BUSL-1.1 (converts to Apache 2.0 after 4 years). Contributions are welcome — from bug reports to new block types.

Ways to contribute

Report bugs

Found something broken? Open an issue on GitHub with steps to reproduce.

Open an issue →

Request features

Have an idea? Open a feature request. Describe the use case, not just the feature.

Request a feature →

Submit a PR

Pick an issue, fork the repo, make your changes, and open a pull request. Start with issues labeled 'good first issue'.

Find good first issues →

Improve docs

Docs live in the engine repo under docs/. Fix a typo, clarify an explanation, or add an example.

View docs source →

Write a blog post or tutorial

Built something with Orch8? Share it. We'll link to community content from the docs.

Let us know →

Build an SDK or integration

The REST API is fully documented. Build an SDK in your language or integrate with your favorite tools.

API reference →

Good first issues

New to Orch8? These issues are scoped, well-described, and have pointers to the relevant code. They're a great way to get familiar with the codebase.

View good first issues on GitHub

Development setup

Orch8 is a multi-crate Rust workspace. You need Rust 1.97 or newer, Docker (for Postgres in tests), and Node.js 18+ (for E2E tests).

Clone and build

Bash

1git clone https://github.com/orch8-io/engine.git
2cd engine
3cargo build --workspace

Run tests

Bash

1# Start Postgres for tests
2docker compose up -d
3
4# Unit tests
5cargo test --workspace
6
7# Linting
8cargo clippy --workspace -- -D warnings
9
10# E2E tests
11cd tests/e2e && npm install && npm test

Run the server locally

Bash

1# With SQLite (no external deps)
2cargo run -- --insecure
3
4# With Postgres
5docker compose up -d
6cargo run

Server runs on port 8080 (HTTP) and 50051 (gRPC) by default. Postgres runs on port 5434 (mapped from container 5432).

Crate structure

Bash

1orch8-server          Binary entry point
2    |
3orch8-api             REST routes (axum) + gRPC services (tonic)
4    |
5orch8-engine          Scheduler, evaluator, handlers, signals, recovery
6    |
7orch8-storage         StorageBackend trait + Postgres + SQLite
8    |
9orch8-types           Domain types, config, errors

Most contributions will touch orch8-engine (new handlers, block types, evaluator logic) or orch8-api (new endpoints). Storage changes require updating both Postgres and SQLite implementations.

Guidelines

✓Open an issue before starting large PRs — let's align on scope first
✓Keep PRs focused — one feature or fix per PR
✓Add tests for new functionality (unit tests in Rust, E2E tests in JS for API changes)
✓Run cargo clippy and cargo fmt before submitting
✓Update docs if your change affects the public API
✓Be respectful in discussions — technical disagreements are welcome, personal attacks are not

License note

By contributing to Orch8, you agree that your contributions will be licensed under the same BUSL-1.1 license. After 4 years, all code (including your contributions) converts to Apache 2.0.