如何为blaze贡献代码：从源码构建、运行测试到合入变更的完整开发者指南

blaze是一个比 cargo/rustc 快至多 92 倍的 Rust 增量构建工具，本文将带你走通为 blaze 贡献代码的全流程：如何从源码构建 blaze、如何运行与 rustc 对照的测试闸门（gate）、以及如何通过 Pull Request 把变更合入主分支，适合想参与这个 Rust 编译器项目的开发者快速上手。

一、先认识仓库布局：blaze 代码放在哪里

在写第一行代码前，先花两分钟了解 docs/contributing.md 中描述的目录结构。这是贡献代码的"地图"，能帮你判断新代码该落在哪个 crate：

一个值得牢记的原则：rustc 是参照物。blaze 的输出必须与 rustc 在真实程序上的行为一致，任何让 harness 与 rustc 出现差异的变更都不会被合入。

二、从源码构建 blaze：一条命令搞定

blaze 只使用一个固定的 nightly 工具链，版本写在 harness/toolchain 这一个文件里（例如nightly-2026-10-27），其余所有地方都读它或从它生成。你不需要自己猜用哪个 Rust 版本。

构建步骤如下：

git clone https://gitcode.com/gh_mirrors/blaze38/blaze && cd blaze cargo +"$(cat harness/toolchain)" build -p blaze-engine --release

cargo +"$(cat harness/toolchain)"会自动选中仓库钉住的 nightly。日常开发建议直接用它产出的cargo build --release构建（harness、闸门和 CI 用的都是它），改完代码后重编很快。

💡 若使用 LLVM 后端，需先在 flake 的开发壳里构建：nix develop -c cargo build -p blaze-engine --release --features llvm，细节见 docs/contributing.md 的 "LLVM for--features llvm" 一节。

三、新代码该放在哪里

blaze 有一条硬规则：no-rustc——blaze 永远不调用 rustc 来编译任何东西（详见 docs/no-rustc.md）。新代码不能给构建流程增加任何走回 rustc 的路径。

• 语言语义类改动（MIR 构建与 pass、借用检查、常量求值、布局）放前端 crate，如 crates/hir-ty/、crates/hir-def/，优先新建独立 crate 而不是继续加长hir-ty。
• blaze 自身机制（代码生成后端、store、daemon、cargo 集成、harness）放各自的独立 crate，一次普通 commit 即可。

四、运行测试：闸门（gate）是什么

blaze 的测试哲学是差分测试：harness/ 下几乎每个脚本都会用 cargo+rustc 构建一个程序，再用 blaze 的产物替换 rustc 的重新构建，运行两者并逐字节比较 stdout、stderr 和退出码——有差异就是失败。完整的清单在 docs/harness.md。

一个变更在合入前需要通过的"闸门"分两层：

1. Rust 单元测试（CI 的 merge gate 也只查这个 + 构建）：

python3 harness/unittests.py # 或等价地： cargo test --release -p blaze-engine -p hir-ty -p hir-def -p parser -p syntax

2. 快速层 harness，在你的 ix VM 中运行（ci.py是唯一权威清单）：

uv run --frozen python harness/ci.py parts '{"tier": "fast"}' uv run --frozen python harness/ci.py run '{"part": "fast"}'

跑 harness 前先设置被测二进制与后端：

export BLAZE_BIN=$PWD/../target/release/blaze-engine export BLAZE_BACKEND=cranelift # 或 llvm（需 BLAZE_OPT=2 BLAZE_EMIT=fast）

📌 每个 harness 都会自动从harness/toolchain选择工具链；建议加RUST_BACKTRACE=0，避免 panic 的堆栈污染对比输出。

五、贡献者必须知道的四条铁律

来自 docs/contributing.md 的 "Rules for code"，也是代码评审的底线：

1. rustc 是参照物：即使 rustc 的行为看起来像意外，blaze 不一致也是 blaze 的错；
2. 绝不猜测：代码生成器没有显式降级的输入会以CodegenError拒绝，而不是尽力猜测——错的猜测是没人看得见的错误编译；
3. 被拒绝的函数是 bug：要列出来修复，而不是设计绕行方案；
4. 通用修复：只针对某个 crate、某个函数名或某个测试打补丁，不算修复。

风格上遵循 rust-analyzer 的指南：cargo fmt --all、不加无理由的新依赖、小而聚焦的变更、注释解释"为什么"而非"改了什么"。

六、合入变更：land.py 一条命令走完 PR 流程

main 分支只通过 Pull Request 前进，任何人都不能直接 push。分支工作完成、本地闸门通过后：

python3 .github/scripts/land.py "这个分支做了什么"

.github/scripts/land.py 会推送分支、创建 PR 并开启 auto-merge；PR 自身的运行（Linux x86-64 上的构建 + 单元测试，约 5 分钟）就是合并闸门，通过后 GitHub 以 merge commit 合入。若失败会打印检查项链接——修好分支再跑一次即可，它还会自动等待合并并打印 commit。

合入后清理现场：删除 worktree、本地分支和 VM。

七、并行协作与提交礼仪

• 一个 lane 一个 worktree（命名blaze-<lane>-<date>），并配独立的CARGO_TARGET_DIR；永远不要git stash（stash 是全仓库共享的一个栈，可能弹走别的 lane 的改动）。
• 小步快跑：频繁通过 PR 合入，而不是攒一个大 PR 等数小时。
• 报告时区分"跑过什么"和"推断了什么"：docs/reports/ 下的报告就是这么写的，这也是它们可信的原因。
• 引用他人思路要署名：commit 消息尾部加Co-authored-by: Name <email>trailer，并说明出处。
• 文档与代码同变：若你的变更使某篇current状态文档失实，要在同一变更中修好它或标记为superseded；python3 tools/docs.py check会在 CI 中校验所有链接与路径。
• blaze 采用MIT / Apache-2.0 双许可，贡献按同样条款接受。

结语：你的第一个 PR 清单

1. ✅git clone并按harness/toolchain钉住的 nightly 构建blaze-engine --release
2. ✅ 复现问题，写出"修复前失败、修复后通过"的最小用例（corpus 函数 / breaker / edit harness 步骤）
3. ✅ 跑通单元测试 + 快速层闸门（Cranelift 与 LLVM 两个后端）
4. ✅cargo fmt --all，顺手把相关文档保持为真
5. ✅land.py提交 PR，等待 merge gate 通过

更多细节随时查 docs/contributing.md、docs/harness.md 与 AGENTS.md，祝你在 blaze 仓库里贡献顺利 🚂