Skip to content

AGENTS.md

Latest commit

 

History

History
85 lines (64 loc) · 3.53 KB

AGENTS.md

File metadata and controls

85 lines (64 loc) · 3.53 KB
Raw

AGENTS.md

Writing this file is not a statement for or against using AI coding agents. People are using them on this repository either way, so this file exists to make sure that when they do, the rules of the project are actually followed.

If you are driving an agent here, you are responsible for its output. Read the diff before you send it.

Answers to the reviewers should be done by a human, not an agent.

1. A PR needs tests

New behavior or a bug fix comes with a test:

  • compiler argument parsing, hashing, cache key computation: a unit test in the mod test block of the file you changed (src/compiler/gcc.rs, src/compiler/nvcc.rs, src/cache/cache.rs, ...)
  • end-to-end behavior (real compiler invocation, cache hit/miss, server lifecycle): tests/system.rs, tests/sccache_args.rs, tests/sccache_cargo.rs, tests/dist.rs, ...

A new compiler flag is not "just a one-liner": if it changes what ends up in the cache key, it needs a test that would catch getting it wrong. A wrong cache key silently hands users someone else's object file.

No tests, no merge.

2. Keep the PR description short

Describe the problem being solved and what changed. That is all.

  • No generated walls of text, no bullet-point summaries of every hunk, no emoji-headed sections.
  • Title: <area>: <what changed>, e.g. nvcc: fix dryrun parsing for CUDA 13.3.
  • Write issue reports, PR descriptions and replies to reviewers in your own words. The point of review is to check that a human understands the change.

3. Keep the code quiet too

Comments explain why, not what. Do not narrate the diff in the source, do not leave "// Step 1: ..." scaffolding behind, and do not add doc comments that only restate the function signature. Match the density of the surrounding file.

4. Run what CI runs

Before sending anything:

cargo fmt -- --check
cargo clippy --locked --all-targets -- -D warnings -A unknown-lints \
    -A clippy::type_complexity -A clippy::new-without-default
cargo test --locked --lib --bins --tests

Also keep in mind:

  • MSRV is the rust-version in Cargo.toml (kept in sync with README.md and the CI toolchain). Do not use newer language or std features.
  • Storage backends are cargo features (s3, gcs, azure, redis, memcached, gha, webdav, oss, cos, dist-client). Code must still build with --no-default-features --features <one>; CI checks each one.
  • New dependencies need a reason in the PR description. Cargo.lock is committed and CI builds --locked.
  • Some tests need real compilers (gcc, clang, msvc, nvcc) or a running server; if you skipped a test locally, say so instead of claiming it passed.

5. Read the docs already in this repo

Before changing anything, look at the Markdown files here - they are the actual rules, this file is only a pointer:

  • README.md - usage, supported compilers, build and install, MSRV
  • docs/Architecture.md - client/server split, how a compilation is cached
  • docs/Caching.md, docs/Configuration.md, docs/Local.md - cache layout and configuration; update these when you add or change a config knob
  • docs/Distributed.md, docs/DistributedQuickstart.md - the scheduler/server side, read before touching src/dist
  • the per-backend docs (docs/S3.md, docs/Gcs.md, docs/Azure.md, docs/Redis.md, docs/Memcached.md, docs/Webdav.md, docs/GHA.md, docs/OSS.md, docs/COS.md, docs/MultiLevel.md) when touching src/cache/*
  • docs/Rust.md, docs/Xcode.md, docs/ResponseFiles.md - compiler-specific behavior
  • docs/Releasing.md