docs: make CONTRIBUTING and Makefile help match real verification gates (#4667)

CONTRIBUTING.md and the Makefile HEADER advertised nonexistent targets
(make clippy, make check) and claimed 'make pre-commit' runs
format + clippy + check + test, while .config/make/pre-commit.mak
actually runs fmt-check + guard scripts + quick-check with no clippy
and no tests. CONTRIBUTING.md also claimed the repository ships an
automated pre-commit git hook, but no hook is versioned.

- Replace phantom targets with the real ones (clippy-check,
  quick-check, compilation-check)
- Document exactly what pre-commit and pre-pr run, gate by gate,
  with an explicit note that pre-commit runs no clippy and no tests
- Point contributors to 'make pre-pr' as the full pre-PR gate
- Rewrite the git-hooks section to say hooks are optional and not
  versioned; setup-hooks only marks an existing hook executable

No make targets were added or changed; docs/help truth only.

Refs: rustfs/backlog#1153 (infra-9), rustfs/backlog#1155

CONTRIBUTING.md

@@ -8,9 +8,9 @@ This guide covers the local development environment and the checks expected befo
 
 **MANDATORY**: All code must be properly formatted before committing. This project enforces strict formatting standards to maintain code consistency and readability.
 
-#### Pre-commit Requirements
+#### Verification Requirements
 
-Before every commit, you **MUST**:
+Before submitting your changes for review, you **MUST**:
 
 1. **Format your code**:
 
@@ -47,33 +47,53 @@ make fmt
 # Check if code is properly formatted
 make fmt-check
 
-# Run clippy checks
+# Run clippy checks (all targets, all features, -D warnings)
-make clippy
+make clippy-check
 
-# Run compilation check
+# Fast workspace compilation check (excludes e2e_test)
-make check
+make quick-check
 
-# Run tests
+# Full compilation check (cargo check --all-targets)
+make compilation-check
+
+# Run tests (shell script tests + workspace tests + doc tests)
 make test
 
-# Run all pre-commit checks (format + clippy + check + test)
+# Fast pre-commit gate — see below for exactly what it runs
 make pre-commit
 
-# Setup git hooks (one-time setup)
+# Full pre-PR gate (pre-commit gates + clippy + tests)
-make setup-hooks
+make pre-pr
 ```
 
-### 🔒 Automated Pre-commit Hooks
+#### What `make pre-commit` and `make pre-pr` actually run
 
-This project includes a pre-commit hook that automatically runs before each commit to ensure:
+`make pre-commit` is the **fast** gate. It runs, in order
+(see `.config/make/pre-commit.mak`):
 
-- ✅ Code is properly formatted (`cargo fmt --all --check`)
+1. `fmt-check` — `cargo fmt --all --check`
-- ✅ No clippy warnings (`cargo clippy --all-targets --all-features -- -D warnings`)
+2. `unsafe-code-check` — `./scripts/check_unsafe_code_allowances.sh`
-- ✅ Code compiles successfully (`cargo check --all-targets`)
+3. `architecture-migration-check` — `./scripts/check_architecture_migration_rules.sh`
+4. `logging-guardrails-check` — `./scripts/check_logging_guardrails.sh`
+5. `tokio-io-uring-check` — `./scripts/check_no_tokio_io_uring.sh`
+6. `doc-paths-check` — `./scripts/check_doc_paths.sh`
+7. `quick-check` — `cargo check --workspace --exclude e2e_test`
 
-#### Setting Up Pre-commit Hooks
+**`make pre-commit` does NOT run clippy and does NOT run any tests.**
+A green `make pre-commit` is not enough to open a pull request.
 
-Run this command once after cloning the repository:
+`make pre-pr` is the **full** gate: it runs all of the guard checks above,
+then `clippy-check` (`cargo clippy --all-targets --all-features -- -D warnings`)
+and `test` (shell script tests, workspace tests excluding `e2e_test`, and doc
+tests). Run `make pre-pr` before opening or updating a pull request — this is
+what CI enforces.
+
+### 🔒 Git Pre-commit Hooks (optional)
+
+Git hooks are **not** versioned in this repository, so a fresh clone has no
+active pre-commit hook. If you add your own `.git/hooks/pre-commit` (a good
+choice is a one-liner that runs `make pre-commit`), you can mark it executable
+with:
 
 ```bash
 make setup-hooks
@@ -85,6 +105,9 @@ Or manually:
 chmod +x .git/hooks/pre-commit
 ```
 
+With or without a hook, the expectation is the same: run `make pre-commit`
+before committing and `make pre-pr` before opening a pull request.
+
 ### 📝 Formatting Configuration
 
 The project uses the following rustfmt configuration (defined in `rustfmt.toml`):
@@ -97,7 +120,7 @@ single_line_let_else_max_width = 100
 
 ### 🚫 Commit Prevention
 
-If your code doesn't meet the formatting requirements, the pre-commit hook will:
+If you set up a pre-commit hook and your code doesn't meet the formatting requirements, the hook will:
 
 1. **Block the commit** and show clear error messages
 2. **Provide exact commands** to fix the issues
@@ -119,9 +142,10 @@ Example output when formatting fails:
 
 1. **Make your changes**
 2. **Format your code**: `make fmt` or `cargo fmt --all`
-3. **Run pre-commit checks**: `make pre-commit`
+3. **Run the fast gate**: `make pre-commit` (no clippy, no tests)
 4. **Commit your changes**: `git commit -m "your message"`
-5. **Push to your branch**: `git push`
+5. **Run the full gate before opening/updating a PR**: `make pre-pr` (clippy + tests)
+6. **Push to your branch**: `git push`
 
 ### 🛠️ IDE Integration
 

Makefile

@@ -64,10 +64,11 @@ How to use me:
 
 	🔧 Code Quality:
 		make fmt                                 # Format code
-		make clippy                              # Run clippy checks
+		make clippy-check                        # Run clippy (all targets, all features, -D warnings)
-		make test                                # Run tests
+		make quick-check                         # Fast workspace compile check (excludes e2e_test)
-		make pre-commit                          # Run fast pre-commit checks
+		make test                                # Script tests + workspace tests + doc tests
-		make pre-pr                              # Run full pre-PR checks
+		make pre-commit                          # Fast gate: fmt-check + guard scripts + quick-check (NO clippy, NO tests)
+		make pre-pr                              # Full pre-PR gate: pre-commit gates + clippy-check + test
 
 	🚀 Quick Start:
 		make build                               # Build RustFS binary