rustfs/CONTRIBUTING.md

RustFS Development Guide

📋 Code Quality Requirements

This guide covers the local development environment and the checks expected before contributing.

Shared Code Standards

All contributions, whether written by a person or generated with assistance, follow the same implementation and Rust style rules, root quality and verification policy, and applicable scoped AGENTS.md files. Repository formatter/lint settings and domain contracts take precedence over personal preferences. Keep style-rule changes in those shared sources rather than maintaining a second version here.

For assisted work, use only repository-maintained skills under .agents/skills/; external skills are not part of this project's workflow. Follow the root instructions and ordinary tools when no repository skill matches.

For client setup and evidence that root/scoped rules are actually loaded, see agent setup and instruction validation. Keep project policy in shared sources rather than copying it into client-specific files.

🔧 Code Formatting Rules

Use the repository formatter and lint configuration for changed code. Follow rust-toolchain.toml; if local and CI results differ, compare compiler, formatter, and Clippy versions as described in the shared style contract.

Verification Requirements

Before submitting changes for review, complete the applicable verification tier for the final diff. Documentation-only changes use documentation checks; they do not require Cargo formatting, compilation, Clippy, or tests.

• For Rust changes, format with the repository configuration and verify with cargo fmt --all --check. Inspect formatter edits and keep unrelated work out of the change.
• For Rust behavior changes, run focused behavioral tests and package-scoped Clippy with the affected targets/features and -- -D warnings. Compilation alone does not check lint policy, and a test filter matching zero tests does not verify behavior.
• Add compilation checks only for affected targets/features not already compiled by those checks. Use supported feature combinations; do not default every contribution to --all-features or full-workspace checks.
• Complete applicable CI gates before merge. Local scope selection does not waive CI requirements or permit weakening a gate.

Quick Commands

We provide convenient Makefile targets for common tasks. Select from them using the verification tier; this is not a checklist to run in full for every change.

# Format all code
make fmt

# Check if code is properly formatted
make fmt-check

# Run workspace clippy checks (all targets, default features, -D warnings)
make clippy-check

# Fast workspace compilation check (excludes e2e_test)
make quick-check

# Full compilation check (cargo check --all-targets)
make compilation-check

# Run tests (shell script tests + workspace tests + doc tests)
make test

# Fast pre-commit gate — see below for exactly what it runs
make pre-commit

# Optional full gate for broad cross-module changes (guards + clippy + tests)
make pre-pr

make test requires cargo-nextest (CI runs it and only nextest honours .config/nextest.toml test-groups). Install it with cargo install cargo-nextest --locked or a prebuilt binary (see https://nexte.st/docs/installation/). To run the plain cargo test fallback anyway (results not authoritative — serialization semantics differ from CI), set RUSTFS_ALLOW_CARGO_TEST_FALLBACK=1.

Some guard checks are Python (test-wiring-check in make pre-commit, plus the security-coverage and scheduled-validation self-tests in make test) and import tomllib, so they need Python 3.11+. Make resolves the interpreter through scripts/python_bin.sh, which prefers a python3.11+ on PATH and otherwise falls back to uv run --python 3.12. macOS ships /usr/bin/python3 at 3.9, so install a newer one (brew install python@3.12) or uv; pin a specific interpreter with RUSTFS_PYTHON=/path/to/python3.12.

For the full test-layer taxonomy (unit / ecstore black-box / e2e / s3s-e2e / S3 compatibility / chaos / fuzz / bench), each layer's entry command, the naming conventions the migration gate depends on, and the serial/nextest rules, see docs/testing/README.md.

For the event, timeout, required-status, and local reproduction matrix, see docs/testing/ci-gates.md.

🔒 Automated Pre-commit Hooks

What make pre-commit and make pre-pr actually run

make pre-commit is the fast gate: formatting, repository guards, and quick workspace compilation. The exact dependencies of each target are maintained in .config/make/pre-commit.mak.

make pre-commit does not replace the scoped Clippy and behavioral test checks applicable to a change.

make pre-pr is the broader local gate: formatting, shared and additional repository guards, clippy-check, and test (script tests, workspace tests excluding e2e_test, and doc tests). Select it only under the root verification policy. It does not reproduce every CI feature/platform/integration lane; CI still runs its configured repository gates.

🔒 Git Pre-commit Hooks (optional)

The optional hook uses the checked-in .pre-commit-config.yaml. Install pre-commit, then run this from the checkout or a linked worktree:

make setup-hooks

The hook runs cargo fmt --all --check when staged files include Rust source. It does not compile the workspace or run tests. Fix formatting with cargo fmt --all, inspect and stage the result, then commit again.

pre-commit install resolves Git's hook directory for linked worktrees and preserves an existing hook in migration mode. If you use core.hooksPath, keep that hook manager and integrate pre-commit run there; the installer refuses to silently replace that configuration.

A local hook provides early formatting feedback. With or without it, follow the verification tiers in AGENTS.md, run relevant behavioral tests, and satisfy the CI merge gates. make pre-commit and make dev-check remain explicit broader commands.

📝 Formatting Configuration

The project uses the following rustfmt configuration (defined in rustfmt.toml):

max_width = 130
fn_call_width = 90
single_line_let_else_max_width = 100

🔄 Development Workflow

1. Make your changes
2. Format changed source with the applicable formatter; for Rust, use make fmt or cargo fmt --all and inspect the diff
3. Run applicable checks using the verification tier in AGENTS.md; use broader gates only when that tier calls for them
4. Complete the applicable adversarial review for non-exempt changes (see AGENTS.md), resolve findings, and rerun checks affected by fixes
5. Commit the verified changes with an English Conventional Commit message; inspect the staged diff first
6. Push and open/update the PR following the Git and PR rules, including authorization requirements for assisted work

🛠️ IDE Integration

VS Code

Install the rust-analyzer extension and add to your settings.json:

{
    "rust-analyzer.rustfmt.extraArgs": ["--config-path", "./rustfmt.toml"],
    "editor.formatOnSave": true,
    "[rust]": {
        "editor.defaultFormatter": "rust-lang.rust-analyzer"
    }
}

Other IDEs

Configure your IDE to:

• Use the project's rustfmt.toml configuration
• Format on save
• Run clippy checks

❗ Important Notes

• Never bypass formatting checks - they are there for a reason
• CI workflows define the checks for each event and changed surface; see CI gates
• Required checks must pass before merge; resolve formatting, lint, and test failures instead of bypassing them
• Consistent formatting improves code readability and reduces merge conflicts

🆘 Troubleshooting

Pre-commit hook not running?

pre-commit validate-config
pre-commit run --all-files
# Inspect any configured hook manager; do not overwrite it.
git config --get core.hooksPath
# Install if no separate hook manager is configured.
make setup-hooks

Formatting issues?

# Format all code
cargo fmt --all

# Check specific issues
cargo fmt --all --check --verbose

Clippy issues?

Replace <crate> with the affected package and add its supported feature selection when needed. Inspect automatic fixes before staging them.

# See detailed clippy output for the affected package
cargo clippy -p <crate> --all-targets -- -D warnings

# Fix automatically fixable issues
cargo clippy --fix -p <crate> --all-targets

Pull Requests

Follow the Git and PR rules and current PR template. Use English Conventional Commit titles, describe the changed behavior, and provide actual verification evidence and material limits. Keep template headings in the template itself rather than maintaining a copied list here.