RustFS 贡献指南开发环境搭建、代码质量门禁与 Pull Request 提交规范【免费下载链接】rustfs2.3x faster than MinIO for 4KB object payloads. RustFS is an open-source, S3-compatible high-performance object storage system supporting migration and coexistence with other S3-compatible platforms such as MinIO and Ceph.项目地址: https://gitcode.com/GitHub_Trending/rus/rustfsRustFS 是一个开源、兼容 S3 的高性能对象存储系统其代码库横跨crates/下数十个工作区 crate 与e2e_test、fuzz等大量测试载体。本指南以仓库根目录的 CONTRIBUTING.md 为骨架系统梳理贡献者在本地开发时必须满足的格式化、Clippy、编译检查与门禁脚本要求并结合Makefile、.config/make/下的真实 target 定义逐条印证。读完本文你将掌握make pre-commit/make pre-pr到底执行了什么、如何配置 VS Code 等 IDE、如何安装可选 Git 钩子以及提交 Pull Request 时必须遵守的英文与模板规范从而以最小成本通过 CI 门禁。一、指南定位与适用场景CONTRIBUTING.md 是面向本地开发环境与提交前检查的开发指南覆盖四类内容代码质量要求rustfmt 格式化规则、Clippy 检查、编译验证自动化门禁make pre-commit快速门禁与make pre-pr完整门禁的实际执行内容以及可选的 Git pre-commit 钩子开发工作流与 IDE 集成从改代码到 push 的完整步骤、VS Code 配置Pull Request 规范标题/描述/注释/提交信息的英文要求与 PR 模板。其中引用的验证分层、命名约定与 CI 门禁矩阵分别见 docs/testing/README.md 与 docs/testing/ci-gates.md两者均真实存在于仓库中。二、代码格式化规则与验证要求强制要求MANDATORY所有代码在提交前必须经过正确格式化。RustFS 通过统一的 rustfmt 配置保证代码一致性CI 管道与 PR 评审都会强制执行相同检查格式化失败会导致 PR 被自动拒绝。2.1 rustfmt 配置项仓库根目录的 rustfmt.toml 定义了项目统一的格式化参数max_width 130 fn_call_width 90 single_line_let_else_max_width 100三个参数的核心影响参数值作用max_width130单行代码最大宽度超出即换行。注意这比 Rust 社区默认的 100 更宽意味着本项目允许更长的行贡献者不应强行按 100 列断行fn_call_width90函数调用参数在未超过该宽度时保持单行与max_width配合控制调用链的换行策略single_line_let_else_max_width100let ... else表达式整体可保持单行的最大宽度该文件同时注释保留了group_imports、imports_granularity、reorder_imports等可选项但目前均未启用贡献者无需手工调整导入排序。2.2 提交前必须执行的验证命令按 CONTRIBUTING.md 要求提交变更供评审前必须依次完成# 1. 格式化代码 cargo fmt --all # 2. 验证格式化结果 cargo fmt --all --check # 3. 通过 clippy 检查全部 target、全部 feature、警告视为错误 cargo clippy --all-targets --all-features -- -D warnings # 4. 确保编译通过 cargo check --all-targets从源码实现看.config/make/lint-fmt.mak 中的对应 target 与之呼应fmt执行cargo fmt --allfmt-check执行cargo fmt --all --checkclippy-check实际执行cargo clippy --all-targets -- -D warnings文档给出的标准命令带--all-featuresMakefile 封装版未显式带该 flag二者对常规改动结果一致但涉及 feature-gated 代码时建议按文档标准命令执行compilation-check执行cargo check --all-targets。三、Makefile 快捷命令速查仓库提供了一组 Makefile target 覆盖常见任务实际定义分散在 .config/make/ 下各.mak文件中# 格式化所有代码 make fmt # 检查代码是否格式化正确 make fmt-check # 运行 clippy 检查all targets、all features、-D warnings make clippy-check # 快速工作区编译检查排除 e2e_test make quick-check # 完整编译检查cargo check --all-targets make compilation-check # 运行测试shell 脚本测试 工作区测试 文档测试 make test # 快速提交前门禁——具体执行内容见下文 make pre-commit # 可选完整门禁适用于跨模块大范围改动pre-commit clippy 测试 make pre-pr各 target 与源码文件的对应关系target实际执行定义位置fmtcargo fmt --all.config/make/lint-fmt.makfmt-checkcargo fmt --all --check同上clippy-checkcargo clippy --all-targets -- -D warnings同上quick-checkcargo check --workspace --exclude e2e_test同上compilation-checkcargo check --all-targets同上testcore-deps script-tests及工作区/文档测试.config/make/tests.makpre-commit15 项守卫 quick-check.config/make/pre-commit.makpre-prpre-commit 全部门禁 clippy test同上setup-hookspre-commit validate-configpre-commit install同上3.1 关于make test的两个前置条件条件一cargo-nextest。make test依赖 cargo-nextestCI 也以 nextest 为准——只有 nextest 会遵循.config/nextest.toml中的 test-group 配置。安装方式cargo install cargo-nextest --locked或使用预编译二进制。若强行使用普通cargo test回退设置RUSTFS_ALLOW_CARGO_TEST_FALLBACK1结果不具备权威性因为其串行化语义与 CI 不一致。条件二Python 3.11。make pre-commit中的test-wiring-check以及make test中的 security-coverage、scheduled-validation 自检都是 Python 脚本如 scripts/check_test_wiring.py它们 importtomllib该标准库仅在 Python 3.11 及以上版本提供。Make 通过 scripts/python_bin.sh 解析解释器其优先级为环境变量RUSTFS_PYTHON若设置则必须满足版本要求python3.14 / python3.13 / python3.12 / python3.11 / python3 / python中第一个版本达标的解释器都不存在时回退到uv run --python 3.12 --no-project python可用RUSTFS_UV_PYTHON覆盖版本。由于 macOS 自带的/usr/bin/python3是 3.9直接跑make pre-commit会报ModuleNotFoundError: No module named tomllib。解决方式安装新版本解释器macOS 上brew install python3.12或安装 uv也可以用RUSTFS_PYTHON/path/to/python3.12显式指定。四、自动化 pre-commit 门禁make pre-commit与make pre-pr到底跑什么4.1make pre-commit快速门禁不跑 clippy、不跑测试按 .config/make/pre-commit.mak 的真实依赖定义make pre-commit依次执行以下守卫文档列出的 8 项核心步骤用加粗标出其余为 Makefile 中额外串联的守卫fmt-check—cargo fmt --all --check.config/make/lint-fmt.makunsafe-code-check—./scripts/check_unsafe_code_allowances.sh校验所有unsafe_code豁免都带有 SAFETY 注释architecture-migration-check—./scripts/check_architecture_migration_rules.sh校验架构迁移护栏logging-guardrails-check—./scripts/check_logging_guardrails.sh校验日志脱敏与噪音回归tokio-io-uring-check—./scripts/check_no_tokio_io_uring.sh确保 tokio io-uring 运行时特性保持移除状态extension-schema-check—./scripts/check_extension_schema_boundaries.sh确保 extension-schema 保持轻量契约 crate 边界doc-paths-check—./scripts/check_doc_paths.sh校验指令/架构文档引用的文件路径真实存在quick-check—cargo check --workspace --exclude e2e_test此外 Makefile 中还串联了error-other-ratchet-check、body-cache-whitelist-check、s3s-footprint-check、fips-wording-check、embedded-secrets-check、test-wiring-check、planning-docs-check等脚本守卫分别在 scripts/ 下有对应.sh/.py实现例如 scripts/check_embedded_secrets.sh 检查是否误提交私钥材料或凭据字面量、scripts/check_fips_wording.sh 防止文档与 crates/kms 过度宣称加密能力。重要边界make pre-commit不运行 clippy也不运行任何测试它不能替代针对具体改动的 scoped Clippy 与测试检查。4.2make pre-pr完整门禁make pre-pr会先运行上述全部守卫检查随后追加clippy-check—cargo clippy --all-targets --all-features -- -D warningsMakefile 封装为cargo clippy --all-targets -- -D warningstest— shell 脚本测试、工作区测试排除e2e_test与文档测试。同时pre-pr还额外包含log-analyzer-rules-check与offline-enrollment-e2e-check两个守卫见 .config/make/pre-commit.mak 的pre-pr依赖列表。使用建议默认情况下在打开或更新 PR 前不要盲目在本地跑make pre-pr。它只应被用于横跨多个模块、影响面无法用定向检查界定的大范围改动具体取舍依据受影响边界与风险来判断CI 仍然会运行其配置的仓库门禁。执行前请先完成 AGENTS.md 中描述的多角色对抗性评审multi-role adversarial review。4.3 Git pre-commit 钩子可选仓库在 .pre-commit-config.yaml 中提供了可选的本地钩子repos: - repo: local hooks: - id: rustfs-fmt-check name: Rust formatting entry: cargo fmt --all --check language: system types: [rust] pass_filenames: false安装方式需要先安装 pre-commitmake setup-hooks该 target 的实际行为见 .config/make/pre-commit.mak是依次执行pre-commit validate-config与pre-commit install。钩子只会在暂存文件中包含 Rust 源码时运行cargo fmt --all --check不会编译工作区或运行测试。格式化失败时用cargo fmt --all修复、检查并重新暂存后再提交。钩子安装时pre-commit install会为 linked worktree 正确解析 Git 的钩子目录并以迁移模式保留已存在的钩子。如果使用了core.hooksPath请保留原有的钩子管理器并在其中集成pre-commit run——安装器会拒绝静默覆盖该配置。五、开发工作流7 步按 CONTRIBUTING.md 的推荐流程修改代码Make your changes格式化代码make fmt或cargo fmt --all按 AGENTS.md 的验证分层选择相关检查需要更广的快速覆盖时使用make pre-commit提交变更git commit -m your message对非豁免变更完成适用的多角色对抗性评审见 AGENTS.md打开/更新 PR 前运行适用的 scoped 检查仅当改动横跨多模块且影响面无法用定向检查界定时才考虑make pre-pr推送分支git push。六、IDE 集成6.1 VS Code安装rust-analyzer扩展并在settings.json中加入{ rust-analyzer.rustfmt.extraArgs: [--config-path, ./rustfmt.toml], editor.formatOnSave: true, [rust]: { editor.defaultFormatter: rust-lang.rust-analyzer } }--config-path ./rustfmt.toml确保 rust-analyzer 使用仓库根目录的项目级 rustfmt 配置即上文max_width 130等参数而不是编辑器默认配置从而与cargo fmt --all的输出保持一致。6.2 其他 IDE通用要求使用项目的rustfmt.toml配置开启保存时自动格式化Format on Save运行 clippy 检查。七、重要注意事项永远不要绕过格式化检查——它们存在是有原因的所有 CI/CD 管道都会强制执行同样的检查格式化检查失败的 PR 会被自动拒绝一致的格式提升代码可读性并减少合并冲突。八、故障排查8.1 pre-commit 钩子不运行pre-commit validate-config pre-commit run --all-files # 检查是否配置了其他钩子管理器不要覆盖它 git config --get core.hooksPath # 若没有独立的钩子管理器再安装 make setup-hooks8.2 格式化问题# 格式化所有代码 cargo fmt --all # 查看具体问题详细模式 cargo fmt --all --check --verbose8.3 Clippy 问题# 查看详细 clippy 输出 cargo clippy --all-targets --all-features -- -D warnings # 自动修复可修复的问题 cargo clippy --fix --all-targets --all-features九、Pull Request 指南9.1 语言要求所有 PR 标题与描述必须使用英文书写原因包括保证跨贡献者一致性、对国际贡献者可访问、更好地与自动化工具和 CI/CD 集成、以及用全球通用语言清晰沟通。代码注释与提交信息同样必须为英文这也是 AGENTS.md 中 Source comments, commits, PR titles, and PR bodies are in English 的仓库级规定。评审讨论中可以使用中文交流但 PR 本身标题、描述与所有正式文档必须为英文。9.2 PR 描述要求标题使用英文遵循 Conventional Commits 格式例如fix: improve s3-tests readiness detection描述使用英文遵循 PR 模板格式代码注释英文提交信息英文。9.3 PR 模板始终使用 PR 模板仓库.github目录下的pull_request_template.md该路径同时被 AGENTS.md 的 Sources of Truth 一节确认为 PR 格式的唯一来源并填写所有小节Type of Change变更类型Related Issues关联 IssueSummary of Changes变更摘要Checklist自检清单Impact影响范围Additional Notes补充说明十、测试分层与 CI 门禁延伸阅读CONTRIBUTING.md 将完整测试分层归纳为单元测试 / ecstore 黑盒测试 / e2e 测试 / s3s-e2e 测试 / S3 兼容性测试 / chaos 测试 / fuzz 测试 / bench 基准测试。每一层的入口命令、迁移门禁依赖的命名约定、以及串行/nextest 规则详见 docs/testing/README.md事件、超时、required-status 状态与本地复现矩阵详见 docs/testing/ci-gates.md。CI 门禁的权威定义位于.github/workflows/ci.yml按 AGENTS.md 的 Sources of Truth 说明。结语RustFS 的贡献门槛本质上由三层组成格式化与编译rustfmt clippy cargo check、脚本化守卫unsafe/架构/日志/文档路径等一揽子检查与测试分层nextest 各层测试。make pre-commit是日常高频使用的快速门禁make pre-pr仅在大范围跨模块改动时按需使用。把 CONTRIBUTING.md 的检查清单固化到本地钩子与 IDE 自动格式化中再配合英文的 Conventional Commits 提交即可大幅降低与 CI 门禁的往返成本。【免费下载链接】rustfs2.3x faster than MinIO for 4KB object payloads. RustFS is an open-source, S3-compatible high-performance object storage system supporting migration and coexistence with other S3-compatible platforms such as MinIO and Ceph.项目地址: https://gitcode.com/GitHub_Trending/rus/rustfs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考