RustFS 开源项目的 Git 与 Pull Request 工程规范：从提交到合入的完整闭环-平芜编程栈

RustFS 开源项目的 Git 与 Pull Request 工程规范：从提交到合入的完整闭环

【免费下载链接】rustfs🚀2.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

导读：本文围绕 RustFS 仓库中的规范主文档 .agents/references/pull-requests.md 展开，系统梳理该项目在提交（commit）、推送（push）、Pull Request、Issue 与 Discussion 动作上的全部硬性规则，包括 PR 提交前预检清单、PR 生命周期管理、Conventional Commits 基线、验证层级（Verification Tier）与本地门禁命令。读者完成后将掌握一套可直接复制的"提交前自检 → 开 PR → 监控 → 合入 → 清理"完整工作流，并理解规则背后的源码与 CI 证据，适合计划向 RustFS 贡献代码的开发者，以及希望借鉴其工程化规范的团队。

一、规范体系：一份主文档，分层权威

RustFS 的 Git 与 PR 规则并非散落各处，而是有明确的单一权威来源（single normative home）：

主文档：.agents/references/pull-requests.md 适用于 commits、pushes、PRs 以及 issue/discussion 动作，文内所有路径均为仓库根目录相对路径（repository-relative）。
根级 AGENTS.md：AGENTS.md 中的 "Git and PR Baseline" 一节是 Git 与 PR 基线的唯一规范出处（single normative home）。根据 .github/AGENTS.md 的明确说明，其他文件不得重复复制这些规则，以避免副本过期导致规范漂移。
任务触发规则：根 AGENTS.md 规定，在提交、推送、创建/更新 PR、或在 PR/Issue/Discussion 上发布内容之前，必须先阅读该主文档；并且引用文档本身不授权任何发布、合并或发布动作——授权来自用户请求与既有授权。

同时，权限边界由用户授权与根AGENTS.md共同约束，GitHub 仓库的"作用域（scope）"由用户请求决定。这套分层设计保证了"规则可追溯、授权不越界"。

二、最终 PR 预检（Final PR Preflight）：提交前的最后一道闸门

在创建或更新 PR 之前，必须复用已经完成的评审与验证结果，逐项确认以下内容：

预检项	具体要求
核实 base 与完整 diff	确认实际 base（通常是`origin/main`），检查完整任务 diff，包括文件名与空白差异（whitespace）
排除无关内容	diff 中不得包含 secrets、日志、生成产物（generated artifacts）与无关修改（unrelated edits）
保留已有 PR 的 base	除非用户明确要求，否则不得更改既有 PR 的 base
验证层级通过	确认最终 diff 已通过根级验证层（见下文"验证层级"），修复任务归属的失败，并补跑缺失的作用域检查
如实上报	若存在未解决的必需检查（required checks）或权限缺口，如实报告，不得通过扩大任务范围来掩盖
提交信息格式	英文 Conventional Commit 标题长度不超过72 字符；使用模板标题（template headings）、真实运行的检查、实质性风险与回滚说明
写库前复核	在写入 GitHub 的前一刻，再次确认 head 与 task diff 未发生变化；只重跑被编辑或相关状态变更所失效的检查

这条预检清单的核心思想是**"先复用、后补缺、写前复核"**：不重复启动新的一轮完整评审，而是信任已完成验证，仅针对新增变更做增量校验。

三、Pull Request 生命周期（Lifecycle）管理

主文档对 PR 从创建到合入后清理的全过程给出了明确节奏：

创建/更新的即时快照：创建或更新 PR 时，包含一次立即执行的检查快照（checks、mergeability、reviews、unresolved threads）。
默认交接而非驻留：除非用户明确要求监控、release 工作流需要监控、或已有自动化接管，PR 打开后即应交接（hand off），交付当前状态与下一个要观察的事件；不得用固定静默期睡眠（quiet-period sleeps）拖延普通交接。
监控采用事件驱动或有界等待：被要求监控时，只上报状态变化、可操作的失败或有意义的长时间延迟，不做无意义的轮询刷屏。
先调查后改码：遇到失败或评审意见，先调查根因再修改代码；修复任务归属问题 → 重跑受影响的验证 → 推送 → 回复或解决线程 → 恢复监控。
合入门禁：未经必需的 reviewer 批准或明确授权，绝不合并（Never merge without required reviewer approval or explicit authority）。
合入后清理：观察到合入成功后，先验证 commit 确实到达 base，再在安全前提下清理任务工作树/分支；对于被关闭的 PR，除非明确授权删除，否则保留未合并的工作（Preserve unmerged work for closed PRs）。

这套生命周期规则与 .agents/skills/pr-review/SKILL.md 中的"处理后续（Handle follow-up）"步骤互相咬合：复审后续提交时，须先 fetch 新 head，并将已评审 SHA 与新 SHA 对比，绝不能用未 fetch 的origin/pull/<N>/headref 作为证据。

四、Git 与 PR 基线（Baseline）：Commit 与 PR 的硬性格式

4.1 Conventional Commits 与 72 字符上限

所有提交遵循 Conventional Commits 规范，subject 不超过72 字符。仓库实际提交风格可参考根 AGENTS.md 与 CONTRIBUTING.md 中给出的示例，例如fix: improve s3-tests readiness detection这类"类型前缀 + 英文短描述"格式。

4.2 全英文原则

源码注释、commit、PR 标题、PR 正文一律使用英文。PR 讨论过程中可以与 reviewer 用中文交流，但正式产物（PR 本身、标题、描述、全部正式文档）必须是英文——这一点在 CONTRIBUTING.md 的 "Pull Request Guidelines" 一节有同样要求。

4.3 模板完整性与`--body-file`

必须保留 .github/pull_request_template.md 中的每一个标题（heading），用不上时以N/A填充，并列出实际运行过的命令。
多行内容一律使用--body-file传文件的方式创建/编辑 PR，禁止把多行文本直接内联到gh pr create/gh pr edit的--body参数中。这与 PR 评审技能中"Always use--body-fileor--input, never inline multiline--body"的要求一致。

4.4 文本与路径卫生

PR/issue/discussion 内容中不得出现字面量序列\n，也不得出现硬换行的散文段落（hard-wrapped prose paragraphs）。
GitHub 内容中不得包含本地绝对路径或工具特有的标签/前缀（tool-specific labels/prefixes）。
评审线程（review threads）在底层问题修复后才可标记解决；若拒绝某条建议，应附上简短的、基于证据的理由回复（a short evidence-based reason）。

五、PR 模板逐节解析：评审者与机器人都在读它

.github/pull_request_template.md 是 RustFS 所有 PR 的格式基准，共 5 个必填区块：

Related Issues：列出关联 issue，例如Fixes #123；无关联时写N/A。
Summary of Changes：描述具体问题与结果行为；若为行为变更，需指明触发该行为的输入或状态与预期结果，并解释新引入的依赖或抽象。
Verification：给出 1–3 条变更行为的具体证据——测试或命令、观察到的结果、该证据防住的回归；bug 修复须记录"修复前失败/修复后通过"或说明为何无法提供；须注明被测试的 commit 与本地改动；未运行的检查与残余风险也要列出；纯文档改动只需列出适用的文档检查。
Impact：说明用户可见、兼容性、API、部署、配置或文档影响；无影响写N/A。
Additional Notes：供评审者参考的补充信息，或N/A。

模板尾部还引导首次贡献者阅读 CODE_OF_CONDUCT.md，并提示阅读 CLA 文档后在 PR 上评论I have read and agree to the CLA.完成签署。仓库.github/ISSUE_TEMPLATE/下同时提供bug_report.md与feature_request.md，与 PR 模板共同构成完整的贡献表单体系。

六、验证层级（Verification Tier）：按 diff 类型选择门禁

根 AGENTS.md 的 "Verification" 一节规定了按最终任务 diff 选择检查的分层原则，作用域AGENTS.md可以增加具体的路径检查，但不得用"通用全工作区门禁"取代本分层：

变更类型	必跑检查
文档与指令类（prose、注释、agent 指令、skill 元数据）	`git diff --check`+ 相关文档 guard/技能校验器；跳过 Cargo 格式化、编译、Clippy、测试与`make pre-commit`/`make pre-pr`
非行为性源码改动	对应语言的格式化/校验器；仅当语法或可执行示例变化时才加编译或 doctest
局部行为改动（Rust）	`cargo fmt --all --check`+ 覆盖该行为的最窄测试；仅当目标、feature、公共 API、错误处理或控制流未被聚焦测试覆盖时，才加包级`cargo check`/Clippy
广泛跨模块改动	默认不运行`make pre-pr`；仅当最终 diff 很宽、跨多模块且定向检查无法界定影响面时才考虑

配套约束还包括：绝不为了变绿而削弱门禁——不得新增 baseline/allowance、压制 lint、忽略测试或放宽断言；除非该策略变更本身就是被评审的任务。根AGENTS.md还禁止提交一次性计划、追踪表、迁移台账、基准快照等碎片，由 scripts/check_no_planning_docs.sh 强制这一边界。

七、本地门禁速查：make pre-commit 与 make pre-pr

CONTRIBUTING.md 给出了本地验证的完整命令矩阵：

# 格式化与校验 cargo fmt --all cargo fmt --all --check cargo clippy --all-targets --all-features -- -D warnings cargo check --all-targets # 等价 Makefile 目标 make fmt make fmt-check make clippy-check make quick-check # cargo check --workspace --exclude e2e_test make compilation-check # cargo check --all-targets make pre-commit # 快速门禁，见下 make pre-pr # 完整门禁 = pre-commit + clippy + tests

其中make pre-commit是"快速门禁"，按序运行（详见 CONTRIBUTING.md 对.config/make/pre-commit.mak的说明）：

fmt-check—cargo fmt --all --check
unsafe-code-check— scripts/check_unsafe_code_allowances.sh
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
extension-schema-check— scripts/check_extension_schema_boundaries.sh
doc-paths-check— scripts/check_doc_paths.sh
quick-check—cargo check --workspace --exclude e2e_test

注意：make pre-commit不运行 clippy 也不运行任何测试，它不能替代针对具体改动的 scoped Clippy 与测试检查。make pre-pr则是完整门禁（pre-commit 的 guard 检查 + clippy-check + test），仅建议用于跨模块的大改动。

此外，仓库还提供可选的 Git 预提交钩子：.pre-commit-config.yaml 中定义的本地钩子rustfs-fmt-check会在暂存文件包含 Rust 源码时运行cargo fmt --all --check（不编译、不跑测试），通过make setup-hooks安装；若使用core.hooksPath，安装器会拒绝静默覆盖既有钩子管理器。

八、CI 强制与工作流改动纪律

根 AGENTS.md 的 "Sources of Truth" 明确：本地门禁以Makefile与.config/make/为准，CI 门禁以 .github/workflows/ci.yml 为准，PR 格式以 .github/pull_request_template.md 为准。这意味着即使本地全绿，最终仍以 CI 配置的仓库门禁为准。

针对.github/workflows/的改动，.github/AGENTS.md 额外规定：

任何改动必须通过actionlint（从仓库根运行）且零发现（zero findings），make pre-pr不覆盖工作流文件，因此这是工作流改动的必需检查；
自定义自托管 runner 标签（sm-standard-*、dind-*）在 .github/actionlint.yaml 中声明，引入新runs-on:标签必须同步声明；
禁止用配置或-ignore掩盖真实发现——必须通过修复工作流本身来让检查通过；
若安装了 shellcheck，actionlint 还会对run:脚本做 lint，这些发现同样属于门禁。

仓库.github/workflows/下还提供了与 PR 流程配套的自动化佐证，例如ci.yml、cla.yml（CLA 检查）、coverage.yml、e2e-*.yml系列，以及被手动禁用的stale.yml（其文件头注释还记录了一次因"仅看文件看不出 Actions 设置里被禁用"而误导审计的教训，说明"仓库状态 ≠ UI 状态"）。

九、PR 评审工作流：工具化闭环

.agents/skills/pr-review/SKILL.md 将上述 PR 规则落实为一套可执行的命令行工作流，可作为贡献者自查的范本：

# 1. 收集 PR 上下文 gh pr view <N> --repo <owner/repo> --json title,author,state,body,additions,deletions,changedFiles,commits,baseRefName,headRefName,baseRefOid,headRefOid gh pr diff <N> --repo <owner/repo> --name-only # 2. 拉取 diff 并分类变更 git fetch <repo-remote> <baseRefName> refs/pull/<N>/head git diff <baseRefOid>...<headRefOid> --stat # 3. 检查 CI 状态 gh pr checks <N> --repo <owner/repo> gh run view --repo <owner/repo> --log-failed --job=<JOB_ID> # 4. 发布评审（一律 --body-file） gh pr review <N> --repo <owner/repo> --request-changes --body-file /tmp/pr_review.md gh pr review <N> --repo <owner/repo> --approve --body-file /tmp/pr_review.md gh pr review <N> --repo <owner/repo> --comment --body-file /tmp/pr_review.md

若需行内评审意见，则按 .agents/skills/pr-review/references/posting.md 构造 JSON 并通过gh api --method POST /repos/{owner}/{repo}/pulls/<N>/reviews --input /tmp/pr_review.json提交，其中commit_id必须绑定到被评审的 head SHA。

评审纪律与 PR 规则互相印证：findings 需要file:line与具体失败场景；没有 findings 也是完整结果，不得为凑数添加风格 nit；发布前须刷新 PR head，若 head 已变化则先评审增量再更新结论。

十、合规要点速查表

维度	硬性要求
提交信息	Conventional Commits，英文，subject ≤ 72 字符
语言	源码注释 / commit / PR 标题 / PR 正文全英文
PR 模板	保留全部标题，用`N/A`填充，列出真实运行的命令
多行内容	`gh pr create`/`gh pr edit`一律`--body-file`
文本格式	禁止字面`\n`、禁止硬换行散文、禁止本地绝对路径、禁止工具前缀
合并前提	必需 reviewer 批准或明确授权
监控方式	事件驱动或有界等待，只上报状态变化与可操作失败
合入后	验证 commit 到达 base，安全时清理工作树/分支；关闭的 PR 保留未合并工作
验证选择	按 diff 类型选层（文档/非行为/局部行为/跨模块），不削弱门禁
工作流改动	过 actionlint 零发现，新 runner 标签在 actionlint.yaml 声明

结语

RustFS 的 Git 与 PR 规范是一个"规则 → 模板 → 工具 → CI"四层闭环：主文档 .agents/references/pull-requests.md 定义行为基线，.github/pull_request_template.md 固化格式，gh命令族与 .agents/skills/pr-review/SKILL.md 提供执行路径，而 .github/workflows/ci.yml 与 actionlint 负责强制落地。对贡献者而言，只需要记住一个核心原则：提交前复用已验证结论、开 PR 后即时交接、合入前核对授权与 diff、合入后验证并清理——其余所有细节，都能在这套分层文档中逐条找到依据。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

RustFS 开源项目的 Git 与 Pull Request 工程规范：从提交到合入的完整闭环