Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -174,13 +174,15 @@ jobs:
- 'PSScriptAnalyzerSettings.psd1'
- '.github/workflows/**'
# Sphinx docs site: the doc sources themselves, plus README.md,
# CONTRIBUTING.md and docs/vllm.md, which pages single-source via
# MyST `{include}` directives, plus the build config/toolchain pins.
# CONTRIBUTING.md, docs/vllm.md and docs/wsl.md, which pages
# single-source via MyST `{include}` directives, plus the build
# config/toolchain pins.
docs:
- 'docs/rocm-docs/**'
- 'README.md'
- 'CONTRIBUTING.md'
- 'docs/vllm.md'
- 'docs/wsl.md'
- '.readthedocs.yaml'
- '.github/workflows/**'

Expand Down
27 changes: 15 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ SPDX-License-Identifier: MIT

# Contributing to ROCm CLI

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.
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

Expand Down Expand Up @@ -36,19 +36,21 @@ fix/vram-probe-fallback

## Development setup

Prerequisites: Rust (see `rust-toolchain.toml` for the pinned version) and [uv](https://github.com/astral-sh/uv) (for prek and scripts).
Prerequisites: Rust (see `rust-toolchain.toml` for the pinned version) and [uv](https://github.com/astral-sh/uv) (for `prek` and the scripts).

```bash
git clone https://github.com/ROCm/rocm-cli
cd rocm-cli
uv tool install prek # or: cargo install --locked prek
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, 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:
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:

```bash
cargo install cargo-about@0.9.1 --locked --features cli # optional, for THIRD_PARTY_NOTICES.txt
Expand All @@ -67,15 +69,15 @@ cargo install hawkeye@7.0.0 --locked # pinned to match the CI license-headers
| `apps/rocm` | Main CLI binary |
| `apps/rocmd` | Background daemon |
| `crates/rocm-core` | Core library |
| `crates/rocm-dash-*` | Dashboard TUI libraries |
| `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.
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 (e.g. `rocmd` must never depend on `rocm`) are enforced by `cargo xtask check-crate-edges` (`xtask/src/crate_edges.rs`).
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, naming the expected location per citation (exactly where depends on its 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) — though it doesn't check the accuracy of the surrounding prose.

Expand All @@ -86,14 +88,14 @@ Every local (relative-path) markdown link and `#anchor` fragment in the repo —
| Component | Command |
| --- | --- |
| Rust (all crates) | `cargo test` |
| Lint + format check | `prek run --all-files` |
| Lint and format check | `prek run --all-files` |

See `docs/testing.md` for the full test guide and `docs/manual-testing.md` for manual QA steps.
See the [test guide](https://github.com/ROCm/rocm-cli/blob/main/docs/testing.md) for the full set of tests and the [manual testing guide](https://github.com/ROCm/rocm-cli/blob/main/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.
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.
Expand All @@ -110,13 +112,14 @@ 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.
See [Commit signatures](https://github.com/ROCm/rocm-cli/blob/main/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`)
- Third-party dependencies recorded in `Cargo.lock`
- License headers on new source files (see `licenserc.toml`)

## Reporting security issues

Expand Down
6 changes: 4 additions & 2 deletions MANIFEST.md
Original file line number Diff line number Diff line change
Expand Up @@ -683,8 +683,10 @@ filesystem: a bind mount or `subPath` volume is enough to make Linux refuse the
hardlink, and `uv` then silently copies. This cache holds every wheel `uv`
downloads — the ROCm SDK and the torch stack included — so it is typically the
largest directory rocm-cli manages, on the order of several GB per SDK version
installed. It is removed by `rocm uninstall` unless `--keep-data` is passed, and
its location can be overridden with `ROCM_CLI_UV_CACHE_DIR`.
installed. It is removed by `rocm uninstall`. On the default layout, the
configuration and data directories are both `~/.rocm`, so keeping it takes
`--keep-data` and `--keep-config` together. Its location can be overridden
with `ROCM_CLI_UV_CACHE_DIR`.

### Lemonade Embeddable Runtime

Expand Down
Loading
Loading