Contributing#

Thank you for your interest in contributing. This page covers 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 the scripts).

git clone https://github.com/ROCm/rocm-cli
cd rocm-cli
uv tool install prek        # alternative: 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. They rewrite the generated file instead of only reporting that it is stale. When that happens, the commit stops so you can re-stage the refreshed file.

The THIRD_PARTY_NOTICES.txt hook also needs the pinned generator. Without it, the hook skips and CI remains the gate:

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

The license-headers hook (hawkeye) runs on both commit and push for matching files. prek runs it like the others, but doesn’t provision the hawkeye binary. Unlike the manifest hooks above, it fails hard instead of skipping when the binary is missing:

cargo install hawkeye@7.0.0 --locked   # pinned to match the CI license-headers job

Workspace layout#

Path

Description

apps/rocm

Main CLI binary

apps/rocmd

Background daemon

crates/rocm-core

Core library

crates/rocm-dash-*

Dashboard terminal user interface (TUI) libraries

crates/rocm-engine-protocol

Engine IPC protocol

engines/

Inference engine adapters (lemonade, vllm)

Module organization#

New subcommands and subsystems default to their own file from day one. Don’t let them grow inside main.rs/lib.rs waiting for a future extraction pass. See docs/architecture.md for the two extraction patterns in use, the current module map, and the module-organization convention in full.

Crate-layering invariants, such as rocmd never depending on rocm, are enforced by cargo xtask check-crate-edges (xtask/src/crate_edges.rs).

docs/architecture.md’s path citations are enforced by cargo xtask check-architecture-doc (xtask/src/architecture_doc.rs). It fails CI if a citation isn’t found where it’s cited, and names the expected location for each citation. Exactly where it looks depends on the citation’s shape: a slash path, a bare filename, or a bare directory name (see citation_exists’s doc comment in that file for the full rule). It doesn’t check the accuracy of the surrounding prose.

Every local (relative-path) Markdown link and #anchor fragment in the repository (outside docs/rocm-docs/, which docs-build covers instead) is checked by the docs-links CI job, configured by lychee.toml (which lists the current exclusions). It runs offline only, so it doesn’t catch broken external https:// links.

Test commands#

Component

Command

Rust (all crates)

cargo test

Lint and format check

prek run --all-files

See the test guide for the full set of tests and the manual testing guide for manual QA steps.

Making changes#

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

  2. Make your changes. Keep commits focused, with 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 Commit signatures 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 recorded in Cargo.lock

  • License headers 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#