[DEV] Add Pre-commit Check before Submit (#1124)

.pre-commit-config.yaml

@@ -0,0 +1,54 @@
+# Pre-commit hooks configuration for Mooncake
+# Install: pip install -r requirements-dev.txt && pre-commit install
+# Run manually: pre-commit run --all-files
+# Note: clang-format should already be available (installed via system packages or dependencies.sh)
+# Exclusions: build artifacts, vendored extern code, generated wheels.
+
+minimum_pre_commit_version: '3.6.0'
+
+ci:
+  autofix_prs: true
+  autoupdate_commit_msg: 'chore: pre-commit autoupdate'
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: '^(build/|extern/|mooncake-wheel/repaired_wheels_.*|.*/build/|FAST25-release/)'
+      - id: end-of-file-fixer
+        exclude: '^(build/|extern/|mooncake-wheel/repaired_wheels_.*|.*/build/|FAST25-release/)'
+      - id: check-yaml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ['--maxkb=1024']
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: ['--fix']
+        exclude: '^(extern/|FAST25-release/)'
+      - id: ruff-format
+        exclude: '^(extern/|FAST25-release/)'
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.6
+    hooks:
+      - id: codespell
+        exclude: '^(extern/|FAST25-release/)'
+        args: ['--ignore-words-list=te,mooncake,KVCache']
+
+  - repo: https://github.com/pre-commit/mirrors-clang-format
+    rev: v19.1.0
+    hooks:
+      - id: clang-format
+        files: '\.(c|cc|cpp|cxx|h|hpp)$'
+        exclude: '^(extern/|build/|.*/build/|FAST25-release/)'
+
+  - repo: https://github.com/cheshirekow/cmake-format-precommit
+    rev: v0.6.13
+    hooks:
+      - id: cmake-format
+        files: 'CMakeLists\.txt|.*\.cmake'
+        exclude: '^(extern/|build/|.*/build/|FAST25-release/)'

CONTRIBUTING.md

@@ -32,6 +32,54 @@ Use a prefixed PR title to indicate the type of changes. Please use one of the f
 
 For major architectural changes (>500 LOC excluding tests), we would expect a GitHub issue (RFC) discussing the technical design and justification.
 
+
+### Development Workflow & Pre-commit Hooks
+
+Mooncake uses [pre-commit](https://pre-commit.com/) to enforce consistent formatting and lightweight static checks across Python, C++ and CMake sources.
+
+#### Included Hooks
+| Type | Tool | Purpose |
+|------|------|---------|
+| Generic | trailing-whitespace / end-of-file-fixer | Basic hygiene |
+| Python | ruff / ruff-format | Lint + format (includes import sorting) |
+| Spelling | codespell | Catch common typos (ignores domain-specific words) |
+| C/C++ | clang-format | Apply style from the repository's `.clang-format` |
+| CMake | cmake-format | Keep build scripts readable |
+| Meta | check-yaml / check-merge-conflict / check-added-large-files | Prevent bad commits |
+
+#### Setup
+```bash
+pip install -r requirements-dev.txt
+pre-commit install
+```
+
+#### Usage
+Run on all files (first run will install hook environments):
+```bash
+pre-commit run --all-files
+```
+Update hook versions occasionally:
+```bash
+pre-commit autoupdate
+git add .pre-commit-config.yaml
+git commit -m "chore: pre-commit autoupdate"
+```
+
+If clang-format is missing, install it (Ubuntu example):
+```bash
+sudo apt-get update && sudo apt-get install -y clang-format
+```
+
+You can temporarily skip hooks:
+```bash
+git commit -m "wip: skipping hooks" --no-verify
+```
+But please avoid using `--no-verify` for routine commits to keep code quality high.
+
+#### CI Integration
+The configuration supports automatic fixing PRs via `pre-commit.ci` if enabled. To activate, add the repository in the pre-commit.ci dashboard; no further changes are needed.
+
+
 ## Code Quality
 
 The PR needs to meet the following code quality standards:

requirements-dev.txt

@@ -0,0 +1,8 @@
+# Development dependencies for Mooncake
+# Install with: pip install -r requirements-dev.txt
+# Then enable hooks: pre-commit install
+pre-commit==3.7.1
+ruff==0.6.9
+codespell==2.2.6
+cmake-format==0.6.13
+# clang-format is provided via system package (e.g., apt install clang-format) or toolchain