开发者指南 / Developer Guide

本文件包含开发者在本仓库中常用的本地检查、Clippy 与工具链设置说明。

架构、稳定契约和主线迭代计划统一见：docs/MAINLINE.md

Clippy & 项目配置

本项目在 crate 根使用了 Clippy 警告（#![warn(clippy::all)] 和 #![warn(clippy::nursery)]），并包含 clippy.toml（msrv = "1.91.0"）。为避免工具链不匹配，推荐使用 Rust 1.91 或更高版本。

设置工具链 (可选)

rustup toolchain install 1.91.0
rustup override set 1.91.0

运行 Clippy (本地检查与自动修复)

cargo clippy --workspace --all-targets
cargo clippy --workspace --all-targets --fix
cargo clippy --workspace --all-targets --fix --tests

构建与测试

cargo build --workspace
cargo test --workspace

回归测试清单（发送/接收）

每次修改 src/core/sender.rs 或 src/core/receiver.rs 后，至少确认：

路径安全：
接收端拒绝路径穿越（..、空段、分隔符注入）。
导出目标存在冲突文件时，返回错误而不是覆盖。
流结束语义：
下载流未收到 Done 时必须报错，不能静默成功。
本地已完整对象分支不能 panic（不得使用不安全 unwrap 假设）。
事件顺序：
至少保证 Started -> Progress -> Completed/Failed 的生命周期语义清晰。
资源清理：
失败或中断后，临时目录（.sendmer-recv-*）应被清理。

建议执行：

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

关键流程说明

sender::send：
校验输入路径，准备 endpoint/store，导入文件后生成 ticket。
发送侧进度由 provider 事件流驱动，不参与主错误控制流。
receiver::receive：
根据 ticket 建立连接，先下载缺失 blob，再导出到目标目录。
导出阶段若遇冲突路径必须失败，并执行临时目录清理。
下载阶段若流异常提前结束（无 Done）必须返回错误。

Git Hooks（提交前自动检查）

可安装本仓库提供的脚本，在 git commit 前自动执行：

cargo fmt --all -- --check
cargo clippy --locked --workspace --all-targets --all-features

安装方式：

bash scripts/install-git-hooks.sh

安装成功后，每次提交都会触发上述检查，任一失败将阻止提交。

发布前检查清单

在创建并推送 v<version> 标签前，按以下顺序确认：

Cargo.toml 的 package 版本与准备创建的标签一致。
go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7
cargo fmt --all -- --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo check --workspace --all-features --bins
cargo test --locked --workspace --all-features --bins --tests --examples
git status --short 为空，且发布说明会包含本次变更和验证结果。

本地质量门通过后，先创建本地标签并运行无上传演练；脚本会在临时 worktree 中校验标签版本并执行同一组质量门禁：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/rehearse-release.ps1 -Tag v0.6.0

演练通过后推送标签；推送标签会触发 release workflow。随后可使用 -RequireRemoteTag -SkipQualityGate 确认远端标签仍指向同一提交。release workflow 会再次校验标签版本与 Cargo.toml，让 quality-gate/create/build/publish 全部使用该标签，并在构建产物上传前执行同一组质量门禁和 .sha256 sidecar 校验。

提交与推送

在本地确认 lint 与测试通过后提交并推送：

git add -A
git commit -m "chore: apply clippy fixes / update README"
git push origin <branch>

FilesExpand file tree

DEVELOPMENT.md

Latest commit

History