为 Transity 贡献代码：从 make 构建、快照测试到提交 PR 的开发者指南-平芜编程栈

为 Transity 贡献代码：从 make 构建、快照测试到提交 PR 的开发者指南

【免费下载链接】TransityKeep track of your 💵, 🕘, 🐖, 🐄, 🍻 on your command line with the plain text accounting tool of the future! 🚀项目地址: https://gitcode.com/gh_mirrors/tr/Transity

Transity 是一款面向未来的纯文本记账工具，让你在命令行里轻松记录和追踪你的 💵 金钱、🕘 时间与各类资产，全部数据以人类可读的 YAML 纯文本保存。如果你想把代码贡献给这个开源项目，却不知道从哪一步开始，这份面向新手的完整指南会带你走通全流程：克隆仓库、用 make 完成构建、跑单元测试与快照测试、更新快照，最后顺利提交你的第一个 Pull Request（PR）。全程无需复杂配置，跟着做就能上手。

快速了解项目：纯文本记账工具的仓库结构

在动手之前，先花两分钟看清 Transity 的代码仓库布局，这会让你后续的贡献事半功倍：

src/：核心 Rust 源码，入口为 main.rs，工具库逻辑在 lib.rs
purescript/：历史版本中用于 CLI 解析的 PureScript 源码，Parser.purs 等文件仍具参考价值
tests/：测试目录，最重要的 cli_snapshots.rs 存放着所有命令行快照测试
examples/：示例账簿文件，如 journal.yaml，是测试与演示的黄金素材
docs_src/：mdBook 格式的官方文档源码，10_Contributing.md 就是贡献者文档
makefile：项目所有开发任务的"控制台"，本文的核心

贡献前准备：克隆仓库与环境要求

贡献的第一步，是获取代码并准备开发环境。使用以下命令克隆 Transity 仓库：

git clone https://gitcode.com/gh_mirrors/tr/Transity cd Transity

你需要在本机安装：

Rust 工具链（含 cargo）：Transity 是 Rust 项目，安装方式可参考官方 rustup 引导脚本
make：多数 Linux/macOS 系统自带；Windows 可借助 Git Bash 或 WSL
可选但推荐：cargo-insta，用于快照测试的交互式审查，安装命令为cargo install cargo-insta

装好后，在项目根目录运行make，它会自动打印出全部可用任务清单，这就是你的"开发地图"。

使用 make 构建 Transity：一条命令完成编译

Transity 把常用操作全部封装进了 makefile，新手不需要记忆冗长的 cargo 参数。以下是几个最高频的目标：

make 目标	作用
`make build`	编译整个项目（先构建服务器端再编译二进制）
`make test`	依次运行单元测试与 CLI 快照测试
`make test-unit`	仅运行单元测试，对应`cargo test --bin transity`
`make test-cli`	仅运行命令行快照测试
`make update-snapshots`	交互式审查并更新快照
`make format`	自动修复代码风格并格式化
`make dev`	启动开发服务器，实时预览效果
`make install`	安装 transity 到系统 PATH
`make docs`	构建 Web 版与官方文档

第一次运行make build可能需要几分钟下载依赖，请耐心等待。编译成功后，你就拥有了一个可运行的 transity 二进制。想立刻体验纯文本记账工具的核心功能？执行make dev即可启动带热重载的开发服务器，或直接运行：

cargo run -- balance examples/journal.yaml

你将看到类似上面截图那样的彩色余额报表。

单元测试与快照测试：保证代码质量的关键

为 Transity 贡献代码，了解它的测试体系是必修课。项目测试分两层：

单元测试

单元测试直接写在源码中。以 src/main.rs 为例，其中包含大量针对金额解析、有理数运算、日期格式化的测试，例如digits_to_rational_137验证数字转有理数，parse_amount_valid验证"15 €"的解析结果。运行命令：

make test-unit

CLI 快照测试

快照测试是 Transity 的重头戏。它位于 tests/cli_snapshots.rs，原理非常直观：测试会实际执行 transity 二进制并捕获其标准输出，然后与预先存储的"快照"文本逐字节比对。比如test_balance运行balance examples/journal.yaml后，调用insta::assert_snapshot!("balance", output)与快照文件 cli_snapshots__balance.snap 比对。

运行全部测试只需一条命令：

make test

如果你新增或修改了某个命令的输出格式，快照测试会立刻"报警"，这正是它存在的意义——防止你无意中破坏已有行为。

更新快照：make update-snapshots 的正确用法

当你有意地改变了命令行输出（比如新增一列、调整对齐、修复了一个格式 bug），旧快照自然不再匹配。此时不要慌，按以下流程更新：

运行make test-cli，确认只有预期中的快照失败
运行make update-snapshots，即cargo insta review
在交互界面中逐个检查差异：y接受新快照，n拒绝，r查看详情
提交时连同.snap快照文件一起推送

⚠️ 重要原则：快照更新必须与代码改动一一对应。如果某个不相关的快照也失败了，说明改动有副作用，请先修复代码，而不是盲目接受快照。

代码风格与格式检查：让提交更规范

Transity 有一套严格且简洁的代码风格——缩进为两个空格，这在 rustfmt.toml 中定义。好在这些全自动：

make format

该命令会先执行cargo clippy --fix --allow-dirty自动修复 lint 警告，再运行cargo fmt统一格式。提交 PR 前务必执行一次，确保通过 CI 的格式检查。

动手实践：从示例账簿理解记账数据

想快速理解纯文本记账工具的数据模型？看 examples/journal.yaml 就够了。它定义了所有者（owner）、实体（entities）与交易（transactions），每笔交易包含 UTC 时间、转账双方与金额。项目还提供了损坏账簿样本 journal-broken-transaction.yaml，用于测试错误处理逻辑——如果你对健壮性改进感兴趣，这里就是绝佳的练手点。