参与贡献

在正确的地方做一处小改动，然后作为 pull request 提交。

开始之前

• 先开一个 issue，或者在已有的 issue 下留言。说明你想改什么、为什么改。
• 等到回复再动手，免得做出来的东西不会被合并。
• 先完成环境搭建，这样你才能构建并运行 HolyArrs。

有问题去 Discord。有想法去 r/HolyArrs。issue 只用来报 bug 和跟踪路线图。

提交你的第一个 pull request

1. 找到你的改动该放的模块。模块里的名字和文件夹名一致，所以 Discord 通知出错，就是改 alerts。

2. 在 app/backend/internal/<module>/ 和 app/frontend/src/lib/<module>/ 里做改动。只做一处修复或一个功能。

3. 先构建 Web 应用，再构建程序，然后在浏览器里试一下改动。见环境搭建。

4. 运行测试里的检查。

   你应该不会看到任何失败。

5. 如果你改了某个页面，就运行它的端到端项目，例如 npm --prefix app/frontend run e2e -- --project=movies。

6. 打开 pull request。关联 issue，说明改了什么、怎么测的，并为这处改动添加或更新测试。

7. 第一次提交 pull request 时，会有机器人请你签署贡献者许可协议。按它的要求回复那一句话就行。

注意

你的作品版权仍然归你。这份协议让 HolyArrs 可以按 AGPL-3.0 和商业许可两种方式提供。合并进来的任何内容也会一直按 AGPL-3.0 提供。协议全文在 .github/CLA.md。

选项

改动该放在哪里

改动	去看
新路由	模块
新模块	模块。先开一个 issue
暂未开放的功能	环境搭建
发布新版本	发布版本。仅限维护者

好的 pull request 是什么样

• 注释要写代码为什么这样做。注释里不要出现路线图编号、日期、人名或破折号。
• 不要动应用里的文字，除非这个 issue 本身就是关于文字的。
• 已发布的 API 路径、字段名、设置键、表名和后台任务名保持原样。只加，不改名。

如果不成功

现象。 某项结构检查失败。 原因。 提示信息里写了是哪个文件、哪条规则。 解决办法。 把代码挪走，或者由高层模块把普通数据传进来。见模块。

现象。 Web 应用看起来是旧的。 原因。 程序提供的是它内嵌的那份构建。 解决办法。 先重新构建 Web 应用，再构建程序。

现象。 端到端测试启动不了。 原因。 测试用的浏览器没有安装。 解决办法。 运行 npx --prefix app/frontend playwright install chromium。

进阶

pull request 必须遵守的规则

• 一个模块只能通过另一个模块的服务（Go）或它的 index.ts（Web）和它打交道。绝不通过它的 store 或它的文件。
• SQL 只放在模块的 store*.go 文件里，只操作这个模块自己的表。
• 一个 Web 组件只有被 2 个或更多模块用到时，才放进 lib/ui。
• 不要 util、common、shared 或 helpers 包。
• 每个对外调用都走 core/outbound。

这些规则有测试把关，所以导入错了构建就会失败。完整列表和检查的名字见模块。

CI 运行什么

任务	运行内容
Web	check、lint、test、build 和端到端测试套件
Go	在 amd64 和 arm64 上运行 go build、go vet 和 go test -timeout 60m ./...，原生和模拟环境下都跑
Race	go test -race ./...
Contract	openapi.json 是否一致、每条路由的权限范围检查、下载器测试套件
Fault and scale	崩溃、写入变慢、外部服务出错和内存方面的测试
Image	构建一个开发镜像，启动它，并让它报出自己的版本

长时间测试的细节见测试。

相关页面

• 环境搭建
• 测试
• 架构