开发规范¶
本页是传习社项目的协作约定概览。目标是让代码历史清晰、评审顺畅，不追求企业级的繁重流程。
分支命名¶
主分支固定为 main。开发从 main 拉出分支，按改动类型加前缀：
示例：
命名用小写英文和连字符，简短描述改了什么。
Commit 信息¶
推荐使用 Conventional Commits 格式：
常用类型：
| 类型 | 用途 |
|---|---|
feat |
新功能 |
fix |
修复问题 |
docs |
文档 |
refactor |
重构 |
test |
测试 |
chore |
杂项 |
示例：
要求：
- 描述用一句话说清做了什么，不要写「update」「fix bug」这类无信息量的内容；
- 一次提交只做一件事，不要把多个不相关的改动混在一起；
- 使用英文或中文皆可，同一项目内保持一致；
- 详细的背景说明写在 Merge Request 描述里，而不是塞进 commit 信息。
协作流程¶
- 先在 Issue 中描述要解决的问题；
- 从
main创建分支，分支名对应 Issue； - 开发并提交，commit 信息按上面的格式书写；
- 推送分支并创建 Merge Request，在描述中关联 Issue；
- 等待评审，根据意见在原分支继续提交；
- 评审通过后合并，删除分支。
各步骤的具体操作见 Issue 与 Merge Request。
几条基本约定¶
不要直接 push main
main 应当始终处于可用状态。所有改动都通过 Merge Request 合入。
- 一个 MR 只解决一个问题。范围越小，评审越快，出问题也越容易定位。
- Commit 信息要可读。半年后回看历史时，能靠它判断每次改动做了什么。
- Code Review 是协作流程，不是找茬。提意见针对代码，接受意见不必介意。
- 不要提交敏感信息与大型二进制文件。详见 Git 基础操作。
- 改动文档与代码同步。行为变了，文档应当一起更新。
关于规范的边界¶
以上是约定，不是硬性门禁。个人实验仓库、临时脚本可以不必严格遵守；共享仓库、会被多人维护的项目请按此执行。
如果某条约定在实际使用中造成明显不便，可以在社内提出讨论修改，规范本身也应当随实践调整。