1. 8.2 如何参与 zhenyi 社区

zhenyi 是作者个人主导的开源项目，规模与资源有限；本节列出对项目长期有用、且对参与者可操作的几种路径。与前言中的定位一致：欢迎 Issue、文档勘误与小步 PR，而不是假设有商业级专职维护团队。

1.1. 8.2.1 参与的方式

开源社区的贡献不只有代码。以下都是有效的贡献：

方式	说明
提 Bug Issue	复现路径清晰时，对维护者与后续读者价值都高
提 Feature Request	写清场景与预期 API，便于权衡是否纳入主线
写文档/教程、勘误书稿	降低新人门槛；本书路径见下「文档贡献」
贡献代码	建议小步 PR，带测试，避免无关重构
分享使用经验、推荐给他人	帮助形成可检索的实践积累

把问题写清楚（环境、复现、预期/实际、日志）通常比一上来大改代码更省时，也更容易被跟进。

1.2. 8.2.2 提交 Issue

1.2.1. 提交 Bug

好的 Bug Issue 包含：

标题：[Bug] 简述问题
正文：
1. 环境（Go 版本、操作系统、zhenyi 版本）
2. 复现步骤（最小可复现的代码）
3. 预期行为
4. 实际行为
5. 错误日志（如果有）
6. 初步分析（可选）

不要担心"我的问题太简单了"或"可能是我用错了"。Issue 是用来确认问题的，不是每个人都正确使用。

1.2.2. 提 Feature Request

标题：[Feature] 功能描述
正文：
1. 解决了什么问题
2. 预期的 API 是什么样子
3. 有什么替代方案（如果你考虑过）
4. 优先级（必须 vs nice to have）

1.3. 8.2.3 贡献代码

1.3.1. 开发环境

git clone https://github.com/aiyang-zh/zhenyi.git
cd zhenyi
go mod download
go test ./...  # 确保所有测试通过

1.3.2. 代码风格

zhenyi 的代码风格遵循 Go 标准：

gofmt 格式化
变量命名：驼峰式，err 非 e
注释：公共 API 需要 godoc 注释
错误处理：error 类型，不用异常

1.3.3. 提 PR 的流程

1. Fork 项目
2. 创建分支：git checkout -b feature/xxx 或 fix/xxx
3. 写代码 + 写测试
4. 确保 go test ./... 通过
5. Push 到你的 Fork
6. 提 PR，描述改动和动机

1.3.4. PR 审查清单

提 PR 前自己检查：

[ ] 代码符合 Go 风格规范
[ ] 有必要的注释（公共 API）
[ ] 有对应的测试
[ ] go test ./... 通过
[ ] 改动范围最小（不要做"顺便优化无关代码"这种事）
[ ] PR 描述清楚改了什么、为什么改

1.4. 8.2.4 文档贡献

文档贡献不需要你会写代码。

1.4.1. 哪些文档值得写

踩坑记录与复现步骤
与具体业务结合的用法说明
双语对照或术语统一
可运行的示例补充（放在 examples/ 并注明与版本的对应关系）

1.4.2. 文档格式

书稿位于仓库内 docs/books/go-actor-realtime/（相对 zhenyi 根目录）。发现与代码或示例不一致时，欢迎按文件提 PR；大幅体例变更可先开 Issue 说明范围，避免与正在进行的章节改版冲突。

1.5. 8.2.5 分享与推广

如果你在实际项目或学习中用了 zhenyi：

在掘金、CSDN、知乎写文章
在 GitHub Issue 里分享使用心得
把 Star 分享给同事
在技术群里讨论

这些都是对项目的帮助。开源项目的价值不只在于代码，更在于有多少人用它、多少人讨论它。

1.6. 8.2.6 社区沟通

目前没有专门的 Slack 或 Discord 群。有问题可以直接：

GitHub Issue（Bug 和 Feature）
GitHub Discussion（一般性讨论）

1.7. 8.2.7 长期维护的思考

一个人维护一个开源项目是困难的。以下是一些降低维护成本的方式：

1.7.1. 自动化

CI/CD 自动测试 + 静态检查
PR 模板自动检查清单
自动发布 Release

1.7.2. 文档优先

很多问题可以通过完善文档解决。如果 FAQ 写得好，可以减少一半的重复 Issue。

1.7.3. 接受不完美

不是每个 Issue 都要马上处理。标记 help wanted 或 good first issue 让社区帮忙。

1.8. 8.2.8 本节要点

Issue 优先写全环境与复现；Feature 写清动机与 API 形状。
PR 小步、可测、go test ./... 通过；公共符号补 godoc。
书稿与 examples/ 对齐能减少重复提问。
沟通以 GitHub Issue / Discussion 为主；维护节奏不保证即时响应。

扩展点与接口名以 8.1 与源码为准；第 7 章示例是验证改动的快捷沙箱。

8.2 如何参与 zhenyi 社区