docs: 新增提交规范

2026-10-04 03:01:42 +08:00 · 2026-09-15 11:41:53 +08:00
parent f35ca1778a
commit ed4c21a68f
3 changed files with 131 additions and 11 deletions
@@ -0,0 +1,112 @@
+# 参与贡献
+
+> 这份文档同时写给人和 AI Agent。文末有给 Agent 的英文硬性规则。
+> 如果你只是想把 TraceMemo 跑起来，看[第一次使用](./docs/user-guide/getting-started.md)就够了。
+
+## 一句话规则
+
+**从 `develop` 拉分支，把 PR 提给 `develop`。**
+
+## 为什么不是 main
+
+| 分支      | 是什么                                                  | 接受 PR 吗     |
+| --------- | ------------------------------------------------------- | -------------- |
+| `main`    | 稳定版。只在发版时更新，对应 GitHub Releases 里的安装包 | 不接受         |
+| `develop` | 开发主线。所有改动先进这里，**随下一个版本一起发布**    | 唯一的目标分支 |
+
+指向 `main` 的 PR、或者不是基于 `develop` 拉出来的分支，会被直接关闭。不是不欢迎贡献，而是因为冲突合并 提交落后较多等原因
+
+## 提 PR 的完整流程
+
+```bash
+# 1. 基于 develop 拉分支（不要基于 main）
+git fetch origin
+git checkout -b feat/your-change origin/develop
+
+# 2. 改代码，只改与本任务相关的文件
+
+# 3. 自检
+pnpm install        # 需要 Node 22 与 pnpm 7.33.7
+pnpm typecheck
+pnpm test:unit      # 再按改动范围补跑 component / integration
+
+# 4. 提交
+git commit -m "feat: 一句话说明改了什么"
+
+# 5. 提 PR，目标分支必须是 develop
+gh pr create --base develop --head feat/your-change
+```
+
+## 提交信息
+
+默认**只写一行标题**：类型前缀 + 一句话说明。
+
+```
+feat: 新增本地查询能力
+fix: 修复查询工具时间契约
+docs: 整理开发文档
+```
+
+确实包含多个功能点时，标题之后每个功能点各写一行纯文本 —— 不要用列表符号，也不要写
+「设置侧：」「测试：」这类分节标题：
+
+```
+feat: 统一手动发送入口为文字转语音
+移除普通文本、图片和本地语音的手动发送入口
+保留文字转语音的生成、试听和发送能力
+```
+
+不要在提交信息里堆文件名清单、测试结果或实现过程叙述，那些属于 PR 描述。
+
+## 分支命名
+
+`feat/…`、`fix/…`、`docs/…`、`refactor/…`，后面接简短的英文或拼音描述。
+
+## PR 前自检
+
+| 你的改动                   | 至少跑这些                                                        |
+| -------------------------- | ----------------------------------------------------------------- |
+| 一般代码 / 服务 / 工具函数 | `pnpm typecheck` + 相关 `pnpm test:unit`                          |
+| 界面 / 交互                | `pnpm typecheck` + 相关 `pnpm test:component`，或针对该功能的 E2E |
+| preload / IPC 契约         | `pnpm typecheck` + 相关 contract 测试或 `pnpm test:integration`   |
+| 只改文档                   | 不需要跑测试                                                      |
+
+全部测试命令见 `package.json` 的 `scripts`；本地开发环境的说明见[开发概览](./docs/development/overview.md)。
+
+## 请不要提交这些东西
+
+- **构建产物**：`out/`、`dist/`、`build/` 下的二进制、`node_modules/`、`test-results/`、`playwright-report/`
+- **真实数据**：微信聊天内容、真实的 wxid / 群名 / 联系人名、聊天截图
+- **密钥**：API Key、Token、数据库密钥、图片解密密钥
+- **本机绝对路径**：`/Users/…`、`C:\Users\…`
+
+测试用的假数据请用一眼能看出是合成的命名，例如 `fixture-group`、`wxid_fixture_member`。
+
+## 合入之后
+
+PR 合进 `develop` 不会立刻出现在下载页，它随**下一个版本**发布。想提前用上，可以自行从
+`develop` 构建。
+
+## 如果你是 AI Agent
+
+请按顺序执行，不要凭直觉选分支：
+
+1. **基线**：`git fetch origin && git checkout -b <branch> origin/develop`。永远不要基于 `main`。
+2. **PR 目标**：`gh pr create --base develop`。无法确定时默认 `develop`；任何情况下都不要把
+   `main` 当 PR 目标。
+3. **改动范围**：只改与本任务相关的文件。不要顺手格式化、重排 import、升级依赖。
+4. **提交前**：跑 `pnpm typecheck` 和与本次改动相关的测试（见上表）。
+5. **提交信息**：一行标题，`type: 描述`。不要写文件清单、测试输出或过程叙述。
+6. **PR 描述**：说明改了什么、为什么改、怎么验证的；关联 Issue 用 `closes #123`。
+7. **禁止**：真实聊天数据、密钥、Token、本机绝对路径、构建产物。
+
+### Hard rules for AI agents (English)
+
+- Base branch: `origin/develop`. Never branch off `main`.
+- Open pull requests with base branch `develop`. PRs targeting `main` are closed without review.
+- One PR = one logical change. No drive-by reformatting, import reordering, or dependency upgrades.
+- Before opening a PR, run `pnpm typecheck` plus the tests relevant to your change.
+- Commit subject: a single line, `type: summary`. No file lists, no test logs, no process narration.
+- Never commit build output (`out/`, `dist/`, `test-results/`, `playwright-report/`), real WeChat
+  data, keys, tokens, or absolute local paths.
+- Changes merged into `develop` ship with the next release.
@@ -161,6 +161,14 @@ TraceMemo 最早叫 **WechatExplorer**。
 | Windows | x64 | `-setup.exe` |
 | macOS | Apple Silicon（M 系列、arm64） | `.dmg` |

+## 参与贡献
+
+稳定版在 `main`，只在发版时更新；所有改动都先进 `develop`，随**下一个版本**一起发布。
+
+**提 PR 请基于 `develop` 拉新分支，并把 PR 的目标分支设为 `develop`** —— 指向 `main` 的 PR 会被直接关闭。
+
+分支流程、提交信息风格、PR 前自检，以及**给 AI Agent 的硬性规则**，都在[参与贡献指南](./CONTRIBUTING.md)。
+
 ## 致谢

 TraceMemo 的诞生离不开开源社区中许多优秀项目的工作。
@@ -34,17 +34,17 @@ pnpm test:e2e:build

 ## 代码变更对应文档

-| 代码区域                                                  | 需要同步检查的文档                                         |
-| --------------------------------------------------------- | ---------------------------------------------------------- |
-| `src/shared/ai-search.ts`、AI Search pipeline             | `user-guide/ai-search.md`、`concepts/answer-sources.md`    |
-| `src/shared/knowledge.ts`、`src/main/knowledge/`          | `user-guide/knowledge.md`、`concepts/how-it-works.md`      |
-| `src/shared/voice-recognition.ts`                         | `user-guide/voice.md`                                      |
-| `src/shared/group-report.ts`、报告 UI                     | `user-guide/report.md`、API/Agent 文档                     |
-| `src/shared/export.ts`、导出服务/UI                       | `user-guide/export.md`                                     |
-| `src/main/services/recall-archive-service.ts`             | `user-guide/privacy.md`                                    |
-| `src/shared/local-api-test.ts`、`src/main/http-server.ts` | `agent/api.md`、`api-security.md`、打包 Skill              |
-| Agent Hub service/UI                                      | `agent/agent-hub.md`、`user-guide/privacy.md`              |
-| 设置导航、连接页面                                        | `user-guide/getting-started.md`、`docs/README.md`          |
+| 代码区域                                                  | 需要同步检查的文档                                      |
+| --------------------------------------------------------- | ------------------------------------------------------- |
+| `src/shared/ai-search.ts`、AI Search pipeline             | `user-guide/ai-search.md`、`concepts/answer-sources.md` |
+| `src/shared/knowledge.ts`、`src/main/knowledge/`          | `user-guide/knowledge.md`、`concepts/how-it-works.md`   |
+| `src/shared/voice-recognition.ts`                         | `user-guide/voice.md`                                   |
+| `src/shared/group-report.ts`、报告 UI                     | `user-guide/report.md`、API/Agent 文档                  |
+| `src/shared/export.ts`、导出服务/UI                       | `user-guide/export.md`                                  |
+| `src/main/services/recall-archive-service.ts`             | `user-guide/privacy.md`                                 |
+| `src/shared/local-api-test.ts`、`src/main/http-server.ts` | `agent/api.md`、`api-security.md`、打包 Skill           |
+| Agent Hub service/UI                                      | `agent/agent-hub.md`、`user-guide/privacy.md`           |
+| 设置导航、连接页面                                        | `user-guide/getting-started.md`、`docs/README.md`       |

 ## 文档检查