mirror of
https://github.com/rustfs/rustfs.git
synced 2026-01-17 01:30:33 +00:00
42 lines
3.7 KiB
Markdown
42 lines
3.7 KiB
Markdown
# Repository Guidelines
|
||
|
||
## ⚠️ Pre-Commit Checklist (MANDATORY)
|
||
**Before EVERY commit, you MUST run and pass ALL of the following:**
|
||
```bash
|
||
cargo fmt --all --check # Code formatting
|
||
cargo clippy --all-targets --all-features -- -D warnings # Lints
|
||
cargo test --workspace --exclude e2e_test # Unit tests
|
||
```
|
||
Or simply run `make pre-commit` which covers all checks. **DO NOT commit if any check fails.**
|
||
|
||
## Communication Rules
|
||
- Respond to the user in Chinese; use English in all other contexts.
|
||
- Code and documentation must be written in English only. Chinese text is allowed solely as test data/fixtures when a case explicitly requires Chinese-language content for validation.
|
||
- **Pull Request titles and descriptions must be written in English** to ensure consistency and accessibility for all contributors.
|
||
|
||
## Project Structure & Module Organization
|
||
The workspace root hosts shared dependencies in `Cargo.toml`. The service binary lives under `rustfs/src/main.rs`, while reusable crates sit in `crates/` (`crypto`, `iam`, `kms`, and `e2e_test`). Local fixtures for standalone flows reside in `test_standalone/`, deployment manifests are under `deploy/`, Docker assets sit at the root, and automation lives in `scripts/`. Skim each crate’s README or module docs before contributing changes.
|
||
|
||
## Build, Test, and Development Commands
|
||
Run `cargo check --all-targets` for fast validation. Build release binaries via `cargo build --release` or the pipeline-aligned `make build`. Use `./build-rustfs.sh --dev` for iterative development and `./build-rustfs.sh --platform <target>` for cross-compiles. Prefer `make pre-commit` before pushing to cover formatting, clippy, checks, and tests.
|
||
Always ensure `cargo fmt --all --check`, `cargo test --workspace --exclude e2e_test`, and `cargo clippy --all-targets --all-features -- -D warnings` complete successfully after each code change to keep the tree healthy and warning-free.
|
||
|
||
## Coding Style & Naming Conventions
|
||
Formatting follows the repo `rustfmt.toml` (130-column width). Use `snake_case` for items, `PascalCase` for types, and `SCREAMING_SNAKE_CASE` for constants. Avoid `unwrap()` or `expect()` outside tests; bubble errors with `Result` and crate-specific `thiserror` types. Keep async code non-blocking and offload CPU-heavy work with `tokio::task::spawn_blocking` when necessary.
|
||
|
||
## Testing Guidelines
|
||
Co-locate unit tests with their modules and give behavior-led names such as `handles_expired_token`. Integration suites belong in each crate’s `tests/` directory, while exhaustive end-to-end scenarios live in `crates/e2e_test/`. Run `cargo test --workspace --exclude e2e_test` during iteration, `cargo nextest run --all --exclude e2e_test` when available, and finish with `cargo test --all` before requesting review. Use `NO_PROXY=127.0.0.1,localhost HTTP_PROXY= HTTPS_PROXY=` for KMS e2e tests.
|
||
When fixing bugs or adding features, include regression tests that capture the new behavior so future changes cannot silently break it.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
Work on feature branches (e.g., `feat/...`) after syncing `main`. Follow Conventional Commits under 72 characters (e.g., `feat: add kms key rotation`). Each commit must compile, format cleanly, and pass `make pre-commit`.
|
||
|
||
**Pull Request Requirements:**
|
||
- PR titles and descriptions **MUST be written in English**
|
||
- Open PRs with a concise summary, note verification commands, link relevant issues
|
||
- Follow the PR template format and fill in all required sections
|
||
- Wait for reviewer approval before merging
|
||
|
||
## Security & Configuration Tips
|
||
Do not commit secrets or cloud credentials; prefer environment variables or vault tooling. Review IAM- and KMS-related changes with a second maintainer. Confirm proxy settings before running sensitive tests to avoid leaking traffic outside localhost.
|