Skip to content

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 Rust workspace with 5 crates. You need Rust 1.75+, Docker (for Postgres in tests), and Node.js 18+ (for E2E tests).

Clone and build

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

Run tests

# Start Postgres for tests
docker compose up -d

# Unit tests
cargo test --workspace

# Linting
cargo clippy --workspace -- -D warnings

# E2E tests
cd tests/e2e && npm install && npm test

Run the server locally

# With SQLite (no external deps)
cargo run -- --insecure

# With Postgres
docker compose up -d
cargo run

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

Crate structure

orch8-server          Binary entry point
    |
orch8-api             REST routes (axum) + gRPC services (tonic)
    |
orch8-engine          Scheduler, evaluator, handlers, signals, recovery
    |
orch8-storage         StorageBackend trait + Postgres + SQLite
    |
orch8-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.