diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bb5d8ac --- /dev/null +++ b/CONTRIBUTING.md @@ -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 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. diff --git a/README.md b/README.md index 615c6fc..c6a3239 100644 --- a/README.md +++ b/README.md @@ -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 的诞生离不开开源社区中许多优秀项目的工作。 diff --git a/docs/development/overview.md b/docs/development/overview.md index 464128d..e98ffc0 100644 --- a/docs/development/overview.md +++ b/docs/development/overview.md @@ -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` | ## 文档检查