Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
224 lines (151 loc) · 5.05 KB

CONTRIBUTING.md

File metadata and controls

224 lines (151 loc) · 5.05 KB

RustFS Development Guide

📋 Code Quality Requirements

For instructions on setting up and running the local development environment, please see Development Guide.

🔧 Code Formatting Rules

MANDATORY: All code must be properly formatted before committing. This project enforces strict formatting standards to maintain code consistency and readability.

Pre-commit Requirements

Before every commit, you MUST:

  1. Format your code:

    cargo fmt --all

  2. Verify formatting:

    cargo fmt --all --check

  3. Pass clippy checks:

    cargo clippy --all-targets --all-features -- -D warnings

  4. Ensure compilation:

    cargo check --all-targets

Quick Commands

We provide convenient Makefile targets for common tasks:

# Format all code
make fmt

# Check if code is properly formatted
make fmt-check

# Run clippy checks
make clippy

# Run compilation check
make check

# Run tests
make test

# Run all pre-commit checks (format + clippy + check + test)
make pre-commit

# Setup git hooks (one-time setup)
make setup-hooks

🔒 Automated Pre-commit Hooks

This project includes a pre-commit hook that automatically runs before each commit to ensure:

  • ✅ Code is properly formatted (cargo fmt --all --check)
  • ✅ No clippy warnings (cargo clippy --all-targets --all-features -- -D warnings)
  • ✅ Code compiles successfully (cargo check --all-targets)

Setting Up Pre-commit Hooks

Run this command once after cloning the repository:

make setup-hooks

Or manually:

chmod +x .git/hooks/pre-commit

📝 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

🚫 Commit Prevention

If your code doesn't meet the formatting requirements, the pre-commit hook will:

  1. Block the commit and show clear error messages
  2. Provide exact commands to fix the issues
  3. Guide you through the resolution process

Example output when formatting fails:

❌ Code formatting check failed!
💡 Please run 'cargo fmt --all' to format your code before committing.

🔧 Quick fix:
   cargo fmt --all
   git add .
   git commit

🔄 Development Workflow

  1. Make your changes
  2. Format your code: make fmt or cargo fmt --all
  3. Run pre-commit checks: make pre-commit
  4. Commit your changes: git commit -m "your message"
  5. Push to your branch: git push

🛠️ 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
  • All CI/CD pipelines will also enforce these same checks
  • Pull requests will be automatically rejected if formatting checks fail
  • Consistent formatting improves code readability and reduces merge conflicts

🆘 Troubleshooting

Pre-commit hook not running?

# Check if hook is executable
ls -la .git/hooks/pre-commit

# Make it executable if needed
chmod +x .git/hooks/pre-commit

Formatting issues?

# Format all code
cargo fmt --all

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

Clippy issues?

# See detailed clippy output
cargo clippy --all-targets --all-features -- -D warnings

# Fix automatically fixable issues
cargo clippy --fix --all-targets --all-features

📝 Pull Request Guidelines

Language Requirements

All Pull Request titles and descriptions MUST be written in English.

This ensures:

  • Consistency across all contributions
  • Accessibility for international contributors
  • Better integration with automated tools and CI/CD systems
  • Clear communication in a globally understood language

PR Description Requirements

When creating a Pull Request, ensure:

  1. Title: Use English and follow Conventional Commits format (e.g., fix: improve s3-tests readiness detection)
  2. Description: Write in English, following the PR template format
  3. Code Comments: Must be in English (as per coding standards)
  4. Commit Messages: Must be in English (as per commit guidelines)

PR Template

Always use the PR template (.github/pull_request_template.md) and fill in all sections:

  • Type of Change
  • Related Issues
  • Summary of Changes
  • Checklist
  • Impact
  • Additional Notes

Note: While you may communicate with reviewers in Chinese during discussions, the PR itself (title, description, and all formal documentation) must be in English.

Following these guidelines ensures high code quality and smooth collaboration across the RustFS project! 🚀