docs: CONTRIBUTING says clippy is not gated at PR time, but ci.yml runs -D warnings clippy on PRs
- Dominant language
- Rust
- Stars
- 467
- Forks
- 54
- Avg merge
- 4h 25m
- Merged PRs (30d)
- 310
Description
## Summary
`CONTRIBUTING.md` tells contributors that clippy is "NOT gated at PR time" and that PR CI runs "only the cheap gates", but `ci.yml` runs a `-D warnings` clippy job on every Rust-touching PR, plus several further PR-time gates the paragraph never mentions. A contributor who trusts CONTRIBUTING is surprised by CI.
## Background
The paragraph describes a CI arrangement that predates the clippy job being re-added to `ci.yml`. The job's own comment even notes it re-adds what earlier issues removed, so the docs and the workflow now disagree.
## Proposed Solution
Rewrite the bullet and the inline comment against the actual PR job list, which is trivially enumerable from `ci.yml`.
## Implementation Notes
- `CONTRIBUTING.md:46`: "cargo clippy --workspace --all-targets ... -D warnings # NOT gated at PR time; yours to run".
- `CONTRIBUTING.md:50`: "PR-time CI runs only the cheap gates ... Clippy and the general unit suite are not enforced on your PR."
- `.github/workflows/ci.yml:53-57` (confirmed): triggers on `pull_request: branches: [main]`.
- `.github/workflows/ci.yml` clippy job runs `cargo clippy -p mlxcel --lib --tests -- -D warnings` (confirmed `-- -D warnings` at `:214`) when Rust files changed.
- Additional PR-time gates unmentioned by the paragraph: `crate-versions`, `kernel-dtype-keys`, `llama-compat-manifest`, `mlx-pin`, `cross-repo-refs` (advisory), `xla-compile`, `xla-link`, `cuda-sm70-compile`.
## Acceptance Criteria
- [ ] CONTRIBUTING's description of PR-time CI matches the jobs `ci.yml` actually runs on PRs.
---
## Original Suggestion
### Title: docs: CONTRIBUTING says clippy is not gated at PR time, but ci.yml runs -D warnings clippy on PRs
`CONTRIBUTING.md` tells contributors that clippy is "NOT gated at PR time" and that PR CI runs "only the cheap gates" — but `ci.yml` runs a `-D warnings` clippy job on every Rust-touching PR, plus seven further PR-time gates the paragraph never mentions. A contributor who trusts CONTRIBUTING gets surprised by CI.
## Evidence
- `CONTRIBUTING.md:46` — "`cargo clippy --workspace --all-targets …` # NOT gated at PR time; yours to run"
- `CONTRIBUTING.md:50` — "PR-time CI runs only the cheap gates: `cargo fmt`, `cargo deny` and a workspace crate-version consistency check … Clippy and the general unit suite are not enforced on your PR."
- `.github/workflows/ci.yml:53-57` — runs on `pull_request: branches: [main]`
- `.github/workflows/ci.yml:155-215` — the `clippy` job runs `cargo clippy -p mlxcel --lib --tests -- -D warnings` when Rust files changed; its own comment at `:207-209` notes it re-adds what earlier issues removed
Additional PR-time `ci.yml` gates unmentioned by the paragraph: `crate-versions` (`:216`), `kernel-dtype-keys` (`:239`), `llama-compat-manifest` (`:260`), `mlx-pin` (`:299`), `cross-repo-refs` (`:345`, advisory), `xla-compile` (`:417`), `xla-link` (`:576`), `cuda-sm70-compile` (`:657`).
## Suggested fix
Rewrite the bullet and the inline comment against the actual job list, which is trivially enumerable from `ci.yml`.
## Acceptance criteria
- [ ] CONTRIBUTING's description of PR-time CI matches the jobs `ci.yml` actually runs on PRs
Contributor guide
Research direction
Read CONTRIBUTING.md around lines 46 and 50, then inspect the pull_request-triggered jobs in .github/workflows/ci.yml, especially the clippy job and its comment. Update the bullet and inline comment so they accurately describe the PR-time jobs and gates. Done means the CONTRIBUTING.md description matches the workflow's actual PR behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, rust
- Domain
- ci-cd, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100