Contributing to Wanaku

Thank you for your interest in contributing to Wanaku. This page directs contributors to the development guides and the minimum validation workflow.

Getting Started

Use Getting Started to run Wanaku and verify an MCP request. It is an operator quick start, not a contributor setup guide.

For implementation work, read the guide that matches the area you plan to change:

Quick Links

• Architecture Overview: filter order, request flow, registries, routing, and feature integration.
• Feature crates: the Feature trait and the feature lifecycle.
• Build a feature crate: a custom feature tutorial.
• Configuration Reference: environment variables, pipeline configuration, and Wanaku bootstrap configuration.
• Admin UI Development: React development, generated API clients, tests, and UI conventions.
• Container Image Build: build the Wanaku container image locally with the Cargo toolchain.
• Build an Admin UI plugin: the local plugin test workflow.
• Admin UI plugin reference: the implemented Web UI plugin contract.
• Evaluators: evaluator configuration, runtime management, and internals.
• Write evaluator actions in JavaScript and in Rust: the action script guides.
• Testing: the workspace, evaluator, semantic router, and Admin UI test suites.
• Write Wanaku documentation: the page conventions and the docs checks.

Prerequisites

Install these tools before you build the workspace:

• Rust 1.96 or later. This is the minimum supported Rust version (MSRV).
• Node.js 22.18.0 or later.
• Yarn classic (1.x).
• cargo-component 0.21.1 and the wasm32-wasip1 target. These build the evaluator WASM actions.

Install the evaluator build tools:

rustup target add wasm32-wasip1
cargo install cargo-component --version 0.21.1 --locked

The default ui feature of wanaku-server embeds the admin UI. When ui/admin/dist/index.html does not exist, cargo build runs yarn install and yarn build in ui/admin. If Yarn is not installed, the build fails with yarn not found.

cargo build also compiles the Rust evaluator actions into actions/dist/. If cargo-component is not installed, the build prints a cargo:warning and continues without the .wasm files. The committed wanaku.yaml refers to these files, so the server does not start with it. The build skips an action when its .wasm file already exists. To rebuild an action after you change it, delete its file in actions/dist/.

Contributor Workflow

1. Build the workspace:

   cargo build

   To build the server without the admin UI and without Yarn, use the headless build:

   cargo build --no-default-features -p wanaku-server

2. Run the Rust tests:

   cargo test

3. Run the evaluator example action tests. These tests need the .wasm files in actions/dist/:

   cargo test -p wanaku-feature-evaluator --lib --test example_actions -- --ignored

4. Check formatting:

   cargo fmt --check

5. Run Clippy for the default build and the headless build:

   cargo clippy --all-targets -- -D warnings
   cargo clippy --all-targets --no-default-features -p wanaku-server -- -D warnings

The .github/workflows/pr-build.yml workflow runs the same checks for each pull request.

Add meaningful tests for new behavior. Update the relevant documentation when you add or change a feature.

For admin UI changes, follow the E2E Tests section in Admin UI Development. At minimum, cover the page title, add flow, and delete flow when the page supports those actions.

Before you submit a pull request, review the diff for unrelated changes. Keep related corrections in the existing commit when the project maintainers ask for amended commits.

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please be respectful and professional in all interactions.

Questions?

If you have questions about contributing, please open an issue on GitHub or join our community discussions.

License

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