Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
191 lines (132 loc) · 3.98 KB

CONTRIBUTING.md

File metadata and controls

191 lines (132 loc) · 3.98 KB
Raw

Contributing to Rustuna

Note

Rustuna is not currently accepting external pull requests. The Optuna maintainers have received a growing number of LLM-generated pull requests in recent years, which has created a substantial review burden. In addition, Rustuna is still at an early stage of development and may undergo significant architectural changes. Accepting external pull requests at this stage could make it difficult to iterate quickly.

We hope to accept external contributions in the future. In the meantime, feedback and suggestions are welcome through GitHub Issues.

Repository layout

  • rustuna_core: Core components and abstractions.
  • rustuna_sampler: Sampler implementations.
  • rustuna_storage: Storage implementations.
  • rustuna_importance: Hyperparameter importance evaluators.
  • rustuna_pyo3: Python bindings.
  • rustuna_js: JavaScript and WebAssembly bindings.

Unless otherwise noted, run the commands below from the repository root.

Rust development

Build

Build the entire workspace:

$ cargo build --workspace

To build a single crate, specify its package name:

$ cargo build -p rustuna_core

Test

Run the Rust test suite with all features enabled:

$ cargo test --all-features

Some storage tests require Python and Optuna. Set up the Python development environment before running these ignored tests:

$ cd rustuna_pyo3
$ uv sync --group dev
$ cd ..
$ source rustuna_pyo3/.venv/bin/activate
$ cargo test -p rustuna_storage -- --ignored

Format and lint

Format the Rust code:

$ cargo fmt --all

Run Clippy with the same options used in CI:

$ cargo clippy --workspace --lib --bins --tests --examples --all-features -- -D warnings

Run an example

$ cargo run -p rustuna_sampler --example quadratic

Profile an example

With cargo-flamegraph installed, generate a flame graph for the sampler example:

$ CARGO_PROFILE_RELEASE_DEBUG=true cargo flamegraph -p rustuna_sampler --example quadratic

Python development

The Python bindings are located in rustuna_pyo3.

Set up the development environment

$ cd rustuna_pyo3
$ uv sync --group dev
$ uv run maturin develop

Test

$ uv run pytest tests/

Format, lint, and type-check

Format the Python code:

$ uv run ruff format .

Run Ruff and mypy:

$ uv run ruff check .
$ uv run mypy rustuna/ python_examples/ tests/

Debug with rust-gdb

$ source .venv/bin/activate
$ RUST_BACKTRACE=1 maturin develop
$ rust-gdb --args python python_examples/simple_quadratic.py

JavaScript and WebAssembly development

The JavaScript and WebAssembly bindings are located in rustuna_js. The build produces two wasm-bindgen packages:

  • pkg/node/ for Node.js
  • pkg/web/ for browsers

The Node.js package is the default entry point. The browser package is available through the rustuna/web subpath and the browser export condition.

Build

The build requires the wasm32-unknown-unknown Rust target and wasm-bindgen-cli.

$ cd rustuna_js
$ pnpm build

Test

$ pnpm test

Format and lint

With Biome installed, format the source files:

$ biome format --write examples/*.ts test/*.mjs

Run the same checks used in CI:

$ biome ci examples/*.ts test/*.mjs
$ tsc --noEmit --project tsconfig.examples.json

Run the examples

To run the Node.js example, build the package and execute the generated bundle:

$ pnpm build
$ node dist/simple_quadratic.js

The TypeScript compiler must be available when running pnpm build; otherwise, the example bundle is not generated.

To serve the browser example locally:

$ pnpm build
$ python3 -m http.server 8000

Then open http://localhost:8000/examples/browser/.