|
|
# Contributing Guide
|
|
|
|
|
|
本仓库已经同时包含服务端、Android 客户端、Web 客户端和本地部署脚本。后续协作必须按下面的规则执行，避免再次出现分支漂移、协议不一致、WIP PR 长期悬挂、本地调试资产误入版本库等问题。
|
|
|
|
|
|
## 基本原则
|
|
|
|
|
|
1. `main` 只接收可合并、可验证、可发布的代码。
|
|
|
2. 一个 `issue` 对应一个主题分支，不要在同一分支里混入多个不相关需求。
|
|
|
3. 本地调试资产不进 Git，包括证书、密钥、构建产物、个人环境配置。
|
|
|
4. 任何跨端协议改动都必须做双端联调，不能只改单边实现。
|
|
|
5. 没做完的工作不要以普通可合并 PR 的形式挂着；未完成状态请使用 Draft 或继续在本地分支开发。
|
|
|
|
|
|
## 分支规则
|
|
|
|
|
|
1. 新功能或修复必须从最新 `main` 切出：
|
|
|
|
|
|
```bash
|
|
|
git fetch origin
|
|
|
git checkout main
|
|
|
git pull --ff-only origin main
|
|
|
git checkout -b emilia-t/issue-<id>-<topic>
|
|
|
```
|
|
|
|
|
|
2. 分支名建议包含作者、issue、主题，例如：
|
|
|
- `emilia-t/issue-7-audio-message`
|
|
|
- `emilia-t/issue-12-notification-sound`
|
|
|
- `emilia-t/issue-18-server-switching`
|
|
|
3. 不要长期复用一个旧分支持续堆新需求。
|
|
|
4. 合并前必须再次同步 `main`，优先用 `rebase`，避免无意义 merge commit：
|
|
|
|
|
|
```bash
|
|
|
git fetch origin
|
|
|
git rebase origin/main
|
|
|
```
|
|
|
|
|
|
## 提交规则
|
|
|
|
|
|
1. 提交应当聚焦单一目的，避免一个提交同时混入协议、UI、美术、文档、重构。
|
|
|
2. 提交信息必须带范围和目的，推荐格式：
|
|
|
- `feat(android): add voice message playback`
|
|
|
- `fix(web): parse Android audio payload correctly`
|
|
|
- `docs: document local debug CA setup`
|
|
|
- `chore(server): tighten message size validation`
|
|
|
3. 不要使用 `update`、`misc`、`fix bug` 这类无信息量的提交说明。
|
|
|
4. 提交前先看一遍差异，确认没有把临时调试代码、个人地址、日志打印一起带上。
|
|
|
|
|
|
## PR 规则
|
|
|
|
|
|
1. PR 标题必须描述结果，不要长期保留 `WIP:` 前缀。
|
|
|
2. 未完成内容请使用 Draft PR；准备好评审后再转正式 PR。
|
|
|
3. PR 描述至少写清楚以下内容：
|
|
|
- 改了什么
|
|
|
- 为什么改
|
|
|
- 怎么验证
|
|
|
- 是否影响协议、兼容性或部署方式
|
|
|
4. 如果 PR 和目标分支冲突，提交人必须先在本地解决冲突，再更新 PR。
|
|
|
5. 如果发现 PR 只包含部分有效改动，而剩余部分与当前主线冲突或重复，应当把有效增量摘到新提交中，而不是强行点合并。
|
|
|
|
|
|
## 验证要求
|
|
|
|
|
|
提交 PR 前，至少执行与你改动范围对应的验证命令，并在 PR 描述里写明结果。
|
|
|
|
|
|
### 服务端
|
|
|
|
|
|
根据改动类型至少做一项：
|
|
|
|
|
|
```bash
|
|
|
dotnet build
|
|
|
dotnet test
|
|
|
```
|
|
|
|
|
|
如果改动涉及消息大小、限流、鉴权、peer 转发或 TLS/WSS，请补充实际联调结果。
|
|
|
|
|
|
### Android 客户端
|
|
|
|
|
|
```bash
|
|
|
cd android-client
|
|
|
./gradlew :app:assembleDebug
|
|
|
```
|
|
|
|
|
|
如果改动涉及以下内容，还需要额外验证：
|
|
|
|
|
|
- 语音消息：Android 发 -> Web 收；Web 发 -> Android 收
|
|
|
- 通知：前台/后台通知、系统通知开关、通知音效预览
|
|
|
- 服务器切换：切换后自动重连、聊天记录按服务器隔离
|
|
|
- WSS 联调：确认 `deploy/certs/android-local/local_ca.crt` 能被 debug 包信任
|
|
|
|
|
|
### Web 客户端
|
|
|
|
|
|
```bash
|
|
|
cd web-client
|
|
|
npm install
|
|
|
npm run build
|
|
|
```
|
|
|
|
|
|
如果改动涉及录音、播放或协议兼容，还要验证：
|
|
|
|
|
|
- Web 发语音 -> Android 收
|
|
|
- Android 发语音 -> Web 收
|
|
|
- 分片消息能正确重组
|
|
|
|
|
|
## 协议改动规则
|
|
|
|
|
|
本项目最容易出问题的部分是“服务端、Android、Web 三端协议不同步”。任何协议改动必须遵守以下要求：
|
|
|
|
|
|
1. 明确改动的是哪一层：
|
|
|
- 握手
|
|
|
- 鉴权签名
|
|
|
- 业务包结构
|
|
|
- 语音标签或分片
|
|
|
- 消息大小限制
|
|
|
2. 修改协议后，至少检查：
|
|
|
- Android 客户端
|
|
|
- Web 客户端
|
|
|
- 服务端解析或转发逻辑
|
|
|
3. 如需兼容旧客户端，必须写清楚退化策略。
|
|
|
4. 不允许只在某一端“默认推断”字段而不在代码或文档中说明。
|
|
|
|
|
|
## 本地调试资产规则
|
|
|
|
|
|
以下内容只允许本地存在，不允许提交到版本库：
|
|
|
|
|
|
- `deploy/certs/`
|
|
|
- `deploy/keys/`
|
|
|
- 本地生成的 `server.pfx`
|
|
|
- `android-client/app/build/`
|
|
|
- `web-client/dist/`
|
|
|
- 调试日志、抓包、临时脚本
|
|
|
|
|
|
Android debug 本地 CA 信任的约定如下：
|
|
|
|
|
|
1. 本地 CA 证书路径固定为 `deploy/certs/android-local/local_ca.crt`
|
|
|
2. 该路径已被 `.gitignore` 覆盖
|
|
|
3. `android-client/app/build.gradle.kts` 会在 `assembleDebug` 时动态生成 debug-only `networkSecurityConfig`
|
|
|
4. release 构建不会信任本地 CA
|
|
|
|
|
|
## 冲突处理建议
|
|
|
|
|
|
如果 PR 已经明显落后于 `main`，不要直接在平台上硬点合并。正确做法：
|
|
|
|
|
|
1. 本地同步最新 `main`
|
|
|
2. 手动解决冲突
|
|
|
3. 重新跑验证
|
|
|
4. 再推回分支
|
|
|
|
|
|
如果发现 PR 中一部分内容已经被主线吸收，另一部分仍有价值，优先做“摘取有效增量”，不要把旧分支整条强行合进来。
|
|
|
|
|
|
## Issue 与关闭规则
|
|
|
|
|
|
1. 处理 issue 前先确认需求边界，避免顺手扩需求。
|
|
|
2. 做完后在 issue 或 PR 中写清楚：
|
|
|
- 实际完成内容
|
|
|
- 验证方式
|
|
|
- 仍未解决的边界
|
|
|
3. 关闭 issue 前，确认代码已经合入目标分支，而不是只停留在本地或个人分支。
|
|
|
|
|
|
## 推荐工作流
|
|
|
|
|
|
1. 从最新 `main` 切分支
|
|
|
2. 只做单一目标改动
|
|
|
3. 本地自测
|
|
|
4. 更新必要文档
|
|
|
5. 同步最新 `main`
|
|
|
6. 再次验证
|
|
|
7. 提交 PR
|
|
|
8. 评审完成后合并
|
|
|
9. 删除分支
|
|
|
|
|
|
## 最低合并清单
|
|
|
|
|
|
合并前至少确认以下事项全部满足：
|
|
|
|
|
|
- 改动范围单一且清晰
|
|
|
- 无本地调试资产入库
|
|
|
- 与改动相关的构建命令已通过
|
|
|
- 协议变更已做跨端验证
|
|
|
- 文档已补齐
|
|
|
- PR 无未处理冲突
|
|
|
- PR 标题和描述可读，不是 `WIP`
|