mirror of
https://wget.la/https://github.com/Wxw-Gu/WechatExplorer
synced 2026-10-03 18:33:14 +08:00
113 lines
5.1 KiB
Markdown
113 lines
5.1 KiB
Markdown
# 参与贡献
|
||
|
||
> 这份文档同时写给人和 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.
|