You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

5.7 KiB

Raw Permalink Blame History Unescape Escape

Contributing Guide

本仓库已经同时包含服务端、Android 客户端、Web 客户端和本地部署脚本。后续协作必须按下面的规则执行，避免再次出现分支漂移、协议不一致、WIP PR 长期悬挂、本地调试资产误入版本库等问题。

基本原则

main 只接收可合并、可验证、可发布的代码。
一个 issue 对应一个主题分支，不要在同一分支里混入多个不相关需求。
本地调试资产不进 Git，包括证书、密钥、构建产物、个人环境配置。
任何跨端协议改动都必须做双端联调，不能只改单边实现。
没做完的工作不要以普通可合并 PR 的形式挂着；未完成状态请使用 Draft 或继续在本地分支开发。

分支规则

新功能或修复必须从最新 main 切出：

git fetch origin
git checkout main
git pull --ff-only origin main
git checkout -b emilia-t/issue-<id>-<topic>

分支名建议包含作者、issue、主题，例如：
- emilia-t/issue-7-audio-message
- emilia-t/issue-12-notification-sound
- emilia-t/issue-18-server-switching
不要长期复用一个旧分支持续堆新需求。
合并前必须再次同步 main，优先用 rebase，避免无意义 merge commit：

git fetch origin
git rebase origin/main

提交规则

提交应当聚焦单一目的，避免一个提交同时混入协议、UI、美术、文档、重构。
提交信息必须带范围和目的，推荐格式：
- 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
不要使用 update、misc、fix bug 这类无信息量的提交说明。
提交前先看一遍差异，确认没有把临时调试代码、个人地址、日志打印一起带上。

PR 规则

PR 标题必须描述结果，不要长期保留 WIP: 前缀。
未完成内容请使用 Draft PR；准备好评审后再转正式 PR。
PR 描述至少写清楚以下内容：
- 改了什么
- 为什么改
- 怎么验证
- 是否影响协议、兼容性或部署方式
如果 PR 和目标分支冲突，提交人必须先在本地解决冲突，再更新 PR。
如果发现 PR 只包含部分有效改动，而剩余部分与当前主线冲突或重复，应当把有效增量摘到新提交中，而不是强行点合并。

验证要求

提交 PR 前，至少执行与你改动范围对应的验证命令，并在 PR 描述里写明结果。

服务端

根据改动类型至少做一项：

dotnet build
dotnet test

如果改动涉及消息大小、限流、鉴权、peer 转发或 TLS/WSS，请补充实际联调结果。

Android 客户端

cd android-client
./gradlew :app:assembleDebug

如果改动涉及以下内容，还需要额外验证：

语音消息：Android 发 -> Web 收；Web 发 -> Android 收
通知：前台/后台通知、系统通知开关、通知音效预览
服务器切换：切换后自动重连、聊天记录按服务器隔离
WSS 联调：确认 deploy/certs/android-local/local_ca.crt 能被 debug 包信任

Web 客户端

cd web-client
npm install
npm run build

如果改动涉及录音、播放或协议兼容，还要验证：

Web 发语音 -> Android 收
Android 发语音 -> Web 收
分片消息能正确重组

协议改动规则

本项目最容易出问题的部分是“服务端、Android、Web 三端协议不同步”。任何协议改动必须遵守以下要求：

明确改动的是哪一层：
- 握手
- 鉴权签名
- 业务包结构
- 语音标签或分片
- 消息大小限制
修改协议后，至少检查：
- Android 客户端
- Web 客户端
- 服务端解析或转发逻辑
如需兼容旧客户端，必须写清楚退化策略。
不允许只在某一端“默认推断”字段而不在代码或文档中说明。

本地调试资产规则

以下内容只允许本地存在，不允许提交到版本库：

deploy/certs/
deploy/keys/
本地生成的 server.pfx
android-client/app/build/
web-client/dist/
调试日志、抓包、临时脚本

Android debug 本地 CA 信任的约定如下：

本地 CA 证书路径固定为 deploy/certs/android-local/local_ca.crt
该路径已被 .gitignore 覆盖
android-client/app/build.gradle.kts 会在 assembleDebug 时动态生成 debug-only networkSecurityConfig
release 构建不会信任本地 CA

冲突处理建议

如果 PR 已经明显落后于 main，不要直接在平台上硬点合并。正确做法：

本地同步最新 main
手动解决冲突
重新跑验证
再推回分支

如果发现 PR 中一部分内容已经被主线吸收，另一部分仍有价值，优先做“摘取有效增量”，不要把旧分支整条强行合进来。

Issue 与关闭规则

处理 issue 前先确认需求边界，避免顺手扩需求。
做完后在 issue 或 PR 中写清楚：
- 实际完成内容
- 验证方式
- 仍未解决的边界
关闭 issue 前，确认代码已经合入目标分支，而不是只停留在本地或个人分支。

最低合并清单

合并前至少确认以下事项全部满足：

改动范围单一且清晰
无本地调试资产入库
与改动相关的构建命令已通过
协议变更已做跨端验证
文档已补齐
PR 无未处理冲突
PR 标题和描述可读，不是 WIP

5.7 KiB Raw Permalink Blame History Unescape Escape