Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
c2f28bf
docs: copyedit new v0.3.0 content and fix the install driver opener
pmoutsias-amd Nov 8, 2026
bfdebac
docs: tighten wording in the WSL, serve-reuse and OOM sections
pmoutsias-amd Nov 8, 2026
343fdda
docs: fold the CLI demo into Getting started and drop the Demos page
pmoutsias-amd Nov 8, 2026
d9aaf5c
docs: make the Model serving and ComfyUI reference easier to scan
pmoutsias-amd Nov 8, 2026
e714c51
docs: point the landing page and nav at reader tasks
pmoutsias-amd Nov 8, 2026
777d818
docs: show the CLI demo on the landing page
pmoutsias-amd Nov 8, 2026
b534f78
docs: add 0.3.0 release notes, release history, and version in the he…
pmoutsias-amd Nov 8, 2026
fa93151
docs: group resolved issues and plain-language the 0.3.0 release notes
pmoutsias-amd Nov 8, 2026
9cc3217
docs: rewrite remaining implementation wording in 0.3.0 release notes
pmoutsias-amd Nov 8, 2026
37d563e
docs: name the MSVC runtime fix in the 0.3.0 release notes
pmoutsias-amd Nov 8, 2026
9dcd5ff
docs: remove the duplicate demo recording from Getting started
pmoutsias-amd Nov 8, 2026
2db5a8b
docs: tighten 0.3.0 release notes wording and add retired driver vari…
pmoutsias-amd Nov 8, 2026
7d6f9b2
docs: tighten README wording for style
pmoutsias-amd Nov 8, 2026
1521e0a
docs: tighten CONTRIBUTING wording for style
pmoutsias-amd Nov 8, 2026
7c265d0
docs: tighten WSL2 page wording for style
pmoutsias-amd Nov 8, 2026
dbc1d41
docs: replace "rather than" in the vLLM adapter page
pmoutsias-amd Nov 8, 2026
66524dd
docs: split dense README paragraphs and add list lead-ins
pmoutsias-amd Nov 8, 2026
c293fd3
docs: split dense CONTRIBUTING paragraphs and add absolute links
pmoutsias-amd Nov 8, 2026
7bc0402
docs: split dense WSL2 page paragraphs
pmoutsias-amd Nov 8, 2026
7e32b00
docs: add First run heading and reorder getting-started sections
pmoutsias-amd Nov 8, 2026
4f0c78d
docs: split dense README command paragraphs and expand acronyms
pmoutsias-amd Nov 8, 2026
4427802
docs: say two binaries, keep both demo GIFs linked, scope fix-21 wording
pmoutsias-amd Nov 9, 2026
20ae558
ci: exclude three front-matter docs pages from the license header check
pmoutsias-amd Nov 9, 2026
7c1b1e7
docs: qualify install driver for WSL2, cover dnf and zypper, expand a…
pmoutsias-amd Nov 10, 2026
b1f6168
docs: link the install driver opener to the WSL page on the site
pmoutsias-amd Nov 10, 2026
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
44 changes: 34 additions & 10 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Bug reports and feature requests are tracked as [GitHub Issues](https://github.c

Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages:

```
```text
feat: add support for vLLM multi-GPU serving
fix: correct VRAM probe when amd-smi is absent
docs: clarify GPU selection flag behavior
Expand All @@ -29,7 +29,7 @@ chore: bump rust-toolchain to 1.96

Branch names should be short and descriptive:

```
```text
feat/vllm-multi-gpu
fix/vram-probe-fallback
```
Expand All @@ -48,7 +48,20 @@ prek install -t pre-push # heavier checks on push (clippy + tests of the crat

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

The pre-push hooks (`cargo clippy`, the e2e harness clippy and `cargo test`) check only the crates your push affects: the crates whose files changed plus every crate that depends on them, selected the way CI's `cargo xtask affected` does. They check the whole workspace when a change cannot be confined to specific crates (the lockfile, the root manifest, the toolchain file, workflow files, a doc an xtask test reads, or a path no crate owns), and when the affected crates cannot be determined at all, for example because the remote branch tip is not fetched locally or the pushed range lists no changed files. They also add the crates whose tests read files from outside their own crate: any Rust file adds `xtask`, whose contract tests scan every source file, and `README.md`, `docs/` and `skills/` add `rocm` and `xtask`. Each step prints the scope it chose and why. A push that changes no Rust file runs none of the cargo steps, whatever else it changes (a lockfile-only push included). A green hook is an early warning and not the gate: on pull requests CI lints the whole workspace, but its Linux test job runs only the affected crates, and the whole workspace's tests run in the Windows debug job, in the merge queue and on `main`. To see what a push would check without compiling anything, run `cargo xtask pre-push-check test --dry-run --base origin/main` (the steps are `clippy`, `clippy-e2e` and `test`).
The pre-push hooks (`cargo clippy`, the e2e harness clippy, and `cargo test`) check only the crates your push affects: the crates whose files changed plus every crate that depends on them, selected the way CI's `cargo xtask affected` does. Each step prints the scope it chose and why.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking, and this one is about the PR description rather than this line. I am anchoring here because a description has no diff line to comment on, and this hunk is part of the CONTRIBUTING.md work in question.

CONTRIBUTING.md takes +34/-10 across two dedicated commits: the pre-push-hook paragraph split into bullets (this hunk), bare paths converted to absolute GitHub links, new lead-ins before the tables and lists, text fences on the commit and branch examples. None of it appears in the description — no bullet mentions the file at all. "Docs only; no code changed" also glosses over the new Python log-filter handler in docs/rocm-docs/conf.py.

Unmentioned work is unreviewed work. Please add a bullet for CONTRIBUTING.md and narrow that final line.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added. The description now has a CONTRIBUTING.md bullet covering the pre-push paragraph split, lead-ins, fence language tags, absolute links, and wording changes, plus a bullet for the html-page-context hook in conf.py. The last line now reads "Docs and Sphinx config only (conf.py, licenserc.toml); no product code changed."


The hooks check the whole workspace when:

- A change cannot be confined to specific crates (the lockfile, the root manifest, the toolchain file, workflow files, a doc an xtask test reads, or a path no crate owns).
- The affected crates cannot be determined at all, for example because the remote branch tip is not fetched locally or the pushed range lists no changed files.

The hooks also add the crates whose tests read files from outside their own crate. Any Rust file adds `xtask`, whose contract tests scan every source file. `README.md`, `docs/`, and `skills/` add `rocm` and `xtask`. A push that changes no Rust file runs none of the cargo steps, whatever else it changes (a lockfile-only push included).

A green hook is an early warning, not the gate. On pull requests, CI lints the whole workspace, but its Linux test job runs only the affected crates. The whole workspace's tests run in the Windows debug job, in the merge queue, and on `main`. To see what a push would check without compiling anything, run the following command (the steps are `clippy`, `clippy-e2e`, and `test`):

```bash
cargo xtask pre-push-check test --dry-run --base origin/main
```

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.

Expand All @@ -58,48 +71,55 @@ The `THIRD_PARTY_NOTICES.txt` hook also needs the pinned generator. Without it,
cargo install cargo-about@0.9.1 --locked --features cli # optional, for THIRD_PARTY_NOTICES.txt
```

The license-headers hook (`hawkeye`) runs on every commit and push, whatever is staged. It has no file-type filter, because `hawkeye` always scans the whole working tree per `licenserc.toml` regardless of which files changed or are staged, including untracked files that aren't gitignored, so an unrelated unheadered file (even one not yet committed) can block an otherwise-unrelated commit. A clean CI checkout never has untracked files, so this hook can be stricter locally than CI is. `prek` runs it like the others, but doesn't provision the `hawkeye` binary. Unlike the manifest hooks above, it fails hard (not just skips) when the binary is missing. It does not check that an installed binary is the pinned version; a mismatched version may run whatever that version's own license-header rules happen to be, which may disagree with CI, or may reject `licenserc.toml` outright. For example, `hawkeye` 6.x rejects this repository's config with `unknown field 'files'`, which blocks every commit and push, not just ones touching code:
The license-headers hook (`hawkeye`) runs on every commit and push, whatever is staged. It has no file-type filter, because `hawkeye` always scans the whole working tree per `licenserc.toml`, including untracked files that aren't gitignored. An unrelated unheadered file, even one not yet committed, can therefore block an otherwise unrelated commit. A clean CI checkout never has untracked files, so this hook can be stricter locally than CI is.

`prek` runs the hook like the others but doesn't provision the `hawkeye` binary. Unlike the manifest hooks above, it fails hard (not just skips) when the binary is missing. It also doesn't check that an installed binary is the pinned version. A mismatched version might apply different license-header rules than CI, or might reject `licenserc.toml` outright. For example, `hawkeye` 6.x rejects this repository's config with `unknown field 'files'`, which blocks every commit and push, not just ones touching code. Install the pinned version:

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

To commit or push without it (for example, while iterating without the binary installed, or on a version it rejects), skip it explicitly: `SKIP=license-headers git commit ...` or `SKIP=license-headers git push`. CI's `license-headers` job still enforces the check either way.

The Markdown-links hook (`lychee`) runs on every commit, over the whole repository rather than just the changed files, since moving or deleting a file can break a link in a Markdown file you didn't touch. It checks your working tree, so a link to a new file you haven't `git add`ed passes locally and still fails in CI. The hook runs `cargo xtask lychee --if-available`. `prek` doesn't provision the binary; without it the hook prints a warning and passes, leaving the `docs-links` CI job as the gate, and a version other than the pinned one runs with a warning:
The Markdown-links hook (`lychee`) runs on every commit, over the whole repository instead of just the changed files, because moving or deleting a file can break a link in a Markdown file you didn't touch. It checks your working tree, so a link to a new file you haven't `git add`ed passes locally and still fails in CI. The hook runs `cargo xtask lychee --if-available`. `prek` doesn't provision the binary; without it the hook prints a warning and passes, leaving the `docs-links` CI job as the gate, and a version other than the pinned one runs with a warning:

```bash
cargo install lychee@0.24.2 --locked # pinned to match the CI docs-links job (lycheeVersion)
```

### Workspace layout

The workspace contains these top-level components:

| 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 |
| `crates/rocm-engine-protocol` | Engine inter-process communication (IPC) protocol |
| `engines/` | Inference engine adapters (lemonade, vllm, aim) |

### 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. Its file links, including every concrete file citation in the per-crate inventories, are checked for resolution (not prose accuracy) by the `docs-links` job below; its section headings and directory names stay bare and unchecked.
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`](https://github.com/ROCm/rocm-cli/blob/main/docs/architecture.md) for the two extraction patterns in use, the current module map, and the module-organization convention in full.

The `docs-links` job below checks the file links in that document, including every concrete file citation in the per-crate inventories. It checks that they resolve, not that the prose is accurate. Its section headings and directory names stay bare and unchecked.

Crate-layering invariants, such as `rocmd` never depending on `rocm`, are enforced by `cargo xtask check-crate-edges` (`xtask/src/crate_edges.rs`). File size is checked by `cargo xtask check-module-size` (`xtask/src/module_size.rs`): no source file may exceed 1,500 production lines, test code excluded, and a change that would cross the limit splits the file instead. Editing a file that is already over the limit does not by itself require a split; those files are split under their own tickets. For now the CI step and the `cargo-module-size` pre-commit hook report offenders without failing.

Every local (relative-path) Markdown link and `#anchor` fragment in the repository (outside `docs/rocm-docs/`, which `docs-build` covers instead, and hidden directories such as `.github/`, which neither check walks) is checked by the `docs-links` CI job and by the `lychee` prek hook above, both configured by `lychee.toml` (which lists the current exclusions). Both run offline only, so they don't catch broken external `https://` links.

Since only links are checked, cite a specific repository file as a link relative to the citing file, `[fix.rs](../crates/rocm-core/src/fix.rs)` from `docs/`, rather than a bare backtick path, which nothing checks. The full rule, including the link forms that fail the check and the places it doesn't apply (`.github/`, links leaving a `skills/` folder, and `docs/rocm-docs/` along with the files it includes, which are this file and README.md), is in AGENTS.md section 5 ("Investigate rocm-cli Before Editing"); it applies to citations you add or edit.
Because only links are checked, cite a specific repository file as a link relative to the citing file, `[fix.rs](../crates/rocm-core/src/fix.rs)` from `docs/`, instead of a bare backtick path, which nothing checks. The full rule, including the link forms that fail the check and the places it doesn't apply (`.github/`, links leaving a `skills/` folder, and `docs/rocm-docs/` along with the files it includes, which are this file and README.md), is in [AGENTS.md](https://github.com/ROCm/rocm-cli/blob/main/AGENTS.md) section 5 ("Investigate rocm-cli Before Editing"); it applies to citations you add or edit.

### Updating the AIM catalog

AIM model entries are hand-maintained in `crates/rocm-core/src/model_catalog.json`;
see `docs/aim-catalog.md` for the refresh process and staleness warning.
AIM model entries are hand-maintained in `crates/rocm-core/src/model_catalog.json`; see [`docs/aim-catalog.md`](https://github.com/ROCm/rocm-cli/blob/main/docs/aim-catalog.md) for the refresh process and staleness warning.

### Test commands

Run the tests with these commands:

| Component | Command |
| --- | --- |
| Rust (all crates) | `cargo test` |
Expand All @@ -109,6 +129,8 @@ See the [test guide](https://github.com/ROCm/rocm-cli/blob/main/docs/testing.md)

## Making changes

To contribute a change:

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.
Expand All @@ -131,6 +153,8 @@ See [Commit signatures](https://github.com/ROCm/rocm-cli/blob/main/docs/commit-s

### What reviewers look for

Reviewers look for the following:

- Tests cover the new behavior
- No secrets, credentials, or internal hostnames in committed files
- Third-party dependencies recorded in `Cargo.lock`
Expand Down
Loading
Loading