常见错误与反面模式

本节汇总了开源贡献中最常见的错误做法，每一条都是从真实项目维护经验中总结出来的。

1. 直接在 main 分支提交代码

严重程度：极高

这是最常见也是危害最大的错误。直接在主分支上修改代码意味着：

• 没有 Code Review
• 其他人的 PR 会产生冲突
• 无法回滚单独的修改
• 项目历史混乱

正确做法

永远通过 Fork → Branch → PR 的流程提交代码，即使你是项目的 collaborator。

2. 把公共仓库当个人笔记

严重程度：极高

有些人获得了仓库的写权限后，就像对待自己的个人项目一样随意修改：

• 随意重命名文件和目录
• 删除"自己觉得没用"的代码
• 大规模重构没有经过讨论
• 添加与项目无关的内容

正确做法

公共项目的每一次修改都需要经过讨论和 Review。重大变更应该先开 Issue 讨论，达成共识后再动手。

3. 无意义的 commit message

严重程度：高

update
fix
1
asdf
修改

这些 commit message 完全没有信息量，半年后没人（包括你自己）能看懂当时改了什么。

正确做法

遵循 Conventional Commits 规范，写清楚类型和描述。

4. 不写 PR 描述直接合并

严重程度：高

空白的 PR 描述意味着：

• 没人知道这次改动的目的
• 无法关联到对应的 Issue
• Review 者需要逐行看代码才能理解意图

正确做法

每个 PR 都应该有清晰的描述，说明改了什么、为什么改、关联哪个 Issue。

5. 不同步上游仓库

严重程度：中

Fork 之后从不同步上游的最新代码，导致：

• 你的分支和上游差异越来越大
• 提交 PR 时出现大量冲突
• 最终可能无法合并

正确做法

定期同步上游代码保持一致：

• 命令行：git fetch upstream && git merge upstream/main
• GitHub 网页：在 Fork 仓库页面点击 Sync fork → Update branch
• GitHub Desktop：切换到 main 分支，选择 Branch → Merge into current branch → upstream/main

6. 一个 PR 包含过多修改

严重程度：中

一个 PR 里塞了几十个文件的修改，涉及多个不相关的功能：

• Review 者无从下手
• 难以定位问题
• 一旦需要回滚，会连带影响其他修改

正确做法

一个 PR 只做一件事。如果有多个修改，拆分成多个 PR 分别提交。