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.

Version Convention

Use a SemVer prerelease suffix for development package versions, such as 0.4.0-dev. Use numbered suffixes for published test releases, such as 0.4.0-alpha.1, 0.4.0-beta.1, and 0.4.0-rc.1. Remove the suffix for a stable release, such as 0.4.0. After the stable release is published, set the next development version, such as 0.5.0-dev.

Internal workspace dependencies use local paths without version requirements. Wanaku crates inherit their package version from workspace.package.version.

Update these files together when you change the version:

• The workspace package version in Cargo.toml.
• The workspace package versions in Cargo.lock.
• The admin UI package version in ui/admin/package.json.

Use the complete development version as the currentDevelopmentVersion input of the early-access workflow. The workflow publishes the rolling early-access release with that version.

CLI download channel

The workspace package version in Cargo.toml selects the CLI download channel. A prerelease version, such as 0.4.0-dev or 0.4.0-rc.1, selects early-access. A stable version, such as 0.4.0, selects stable. Build metadata, such as +build.1, does not change the channel. The Cargo build profile does not select the channel.

Keep CLI_VERSION in ui/admin/src/Pages/Downloads/downloads.ts set to the required Barn CLI version. The Barn CLI version is independent of the server version.

Before you package a server binary, run make build from the repository root. This command rebuilds the admin UI before it compiles the server. If you build with Cargo directly, first run yarn --cwd ui/admin build. Cargo can reuse an existing ui/admin/dist directory. The release and early-access workflows rebuild the UI before they compile the server.

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.