Contributing

Contributing#

Thank you for your interest in contributing. This document explains how to get started, how work is tracked, and what to expect from the review process.

Code of Conduct#

By participating in this project you agree to abide by the Code of Conduct.

Issue tracking#

Bug reports and feature requests are tracked as GitHub Issues. Before opening a new issue, search existing ones to avoid duplicates.

Branch and commit naming#

Use Conventional Commits for commit messages:

feat: add support for vLLM multi-GPU serving
fix: correct VRAM probe when amd-smi is absent
docs: clarify GPU selection flag behavior
chore: bump rust-toolchain to 1.96

Branch names should be short and descriptive:

feat/vllm-multi-gpu
fix/vram-probe-fallback

Development setup#

Prerequisites: Rust (see rust-toolchain.toml for the pinned version) and uv (for prek and scripts).

git clone https://github.com/ROCm/rocm-cli
cd rocm-cli
uv tool install prek        # or: cargo install --locked prek
prek install                # fast checks on every commit
prek install -t pre-push    # heavier checks on push (clippy + tests)

prek runs the same checks locally that CI enforces: cargo fmt, clippy, cargo test, ruff (Python), shellcheck (shell), PowerShell syntax, and the generated manifests (MANIFEST.md, THIRD_PARTY_NOTICES.txt).

The manifest hooks only run when you change the dependency graph, and they rewrite the generated file rather than just reporting it stale — when that happens the commit stops so you can re-stage the refreshed file. THIRD_PARTY_NOTICES.txt additionally needs the pinned generator; without it that hook skips and CI remains the gate:

cargo install cargo-about@0.9.1 --locked --features cli   # optional, for THIRD_PARTY_NOTICES.txt

Workspace layout#

Path

Description

apps/rocm

Main CLI binary

apps/rocmd

Background daemon

crates/rocm-core

Core library

crates/rocm-dash-*

Dashboard TUI libraries

crates/rocm-engine-protocol

Engine IPC protocol

engines/

Inference engine adapters (lemonade, vllm)

Test commands#

Component

Command

Rust (all crates)

cargo test

Lint + format check

prek run --all-files

See docs/testing.md for the full test guide and docs/manual-testing.md for manual QA steps.

Making changes#

  1. Fork the repository and create a branch from main.

  2. Make your changes. Keep commits focused — one logical change per commit.

  3. Add or update tests for any new behavior.

  4. Run the relevant test suite before opening a PR.

  5. Open a pull request against main with a clear title and description following the Conventional Commits format.

Commit signing and sign-off#

Commits must be both cryptographically signed and carry a Developer Certificate of Origin (DCO) Signed-off-by trailer. Use git commit -s to add the trailer automatically. This is enforced by the prek hooks and by a blocking CI check.

Enable SSH signing once with:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

See docs/commit-signatures.md for GPG signing, GitHub “Verified” status, and troubleshooting.

What reviewers look for#

  • Tests cover the new behavior

  • No secrets, credentials, or internal hostnames in committed files

  • Third-party dependencies declared in Cargo.lock; license headers present on new source files (see licenserc.toml)

Reporting security issues#

Do not open a public GitHub Issue for security vulnerabilities. See SECURITY.md for the responsible disclosure process.

License#

By contributing you agree that your contributions will be licensed under the MIT License.

More docs#

  • Testing and verification: docs/testing.md

  • Developer manual QA: docs/manual-testing.md

  • Engine plugin policy: docs/engine-plugins.md

  • vLLM adapter: docs/vllm.md

Contents