工具-05-GitHub与GitLab协作
这篇笔记讲什么
Git 是本地的版本控制工具,而团队协作发生在托管平台上。本篇讲清托管平台在协作中的真实位置(不只是存代码),对比 GitHub / GitLab / Gitee 的定位与访问现实,给出仓库结构与分支策略的取舍,把 Pull Request(PR)/ Merge Request(MR)的完整流程、三种合并方式、Code Review 方法论、Issue 管理、开源协作礼仪,以及「误提交密钥」「强推公共分支」这两类高危事故讲透。
前置:工具-01-Git版本控制(暂存区、分支、合并与变基)。本篇不再重复 Git 命令原理。
是什么
代码托管平台(code hosting platform)是运行 Git 服务的网站,在裸仓库之上加了一整套协作层:
| 层次 | 裸 Git 仓库(git init --bare) | 托管平台额外提供 |
|---|---|---|
| 代码存储 | ✅ | ✅ |
| 权限控制 | 靠 SSH/文件权限 | 细粒度角色(Read / Triage / Write / Maintain / Admin) |
| 代码评审 | ❌ | Pull Request / Merge Request + 行内评论 |
| 任务管理 | ❌ | Issue、标签、里程碑、看板、Projects |
| 自动化 | ❌ | CI/CD 流水线、分支保护、必需检查 |
| 发布 | 手动打 tag | Releases、制品仓库、Pages |
| 协作发现 | ❌ | Fork、Star、搜索、讨论区、安全公告 |
一句话:平台把「一群人改同一份代码」从技术问题变成了流程问题。
为什么需要它
如果只有 Git 而没有平台,团队协作会退回成三种原始形态,各自都有致命问题:
| 原始形态 | 具体做法 | 问题 |
|---|---|---|
| 直接推主干 | 所有人 git push 到 main | 无评审、无 CI,任何人一个笔误污染所有人 |
| 邮件发补丁 | git format-patch + 邮件列表 | 门槛高,讨论与代码分离(Linux 内核至今如此,但普通人学不动) |
| 共享目录捞代码 | 各自提交到自己的分支再口头通知 | 谁改了什么无人知晓,无法追溯 |
平台解决的核心问题是把「代码变更」变成一个有状态、可讨论、可自动校验的对象——也就是 PR/MR。它的价值在于:
- 变更可被拒绝:合并前就拦住错误,而不是上线后回滚;
- 讨论与代码绑定:三个月后还能查到「这行为什么这么写」;
- 责任可追溯:谁批准、谁合并、什么时候,全有记录;
- 自动化有挂载点:CI 在 PR 上跑,绿了才允许合并(见 工具-08-CICD入门)。
一句话记住
PR/MR 是团队协作的基本单元,不是「把代码推上去」的附属步骤。学会用 GitHub/GitLab 的本质是学会如何让一次变更被安全地接受。
核心内容
平台对比
| 维度 | GitHub | GitLab | Gitee(码云) |
|---|---|---|---|
| 定位 | 全球最大开源社区 + 商业托管 | 一体化 DevOps 平台,可自托管 | 国内托管平台 |
| 中文界面 | 有(docs.github.com/zh,站点可切换语言) | 部分中文文档 | 原生中文 |
| 私有仓库 | 免费账号可建无限私有仓库 | 免费账号可建,自托管社区版功能完整 | 免费账号私有仓库数量有限制 |
| CI 能力 | GitHub Actions(.github/workflows/) | GitLab CI/CD(.gitlab-ci.yml,能力更强,含环境、审批、Review App) | Gitee Go(能力相对基础) |
| 自托管 | GitHub Enterprise Server(商业授权) | GitLab Self-Managed(社区版免费) | 企业版/私有部署 |
| 生态 | Actions 市场、Codespaces、Packages | 内置 Container Registry、Pages、安全扫描、Issue 看板 | 国内生态、与国内云服务集成 |
| 中国大陆访问 | 可能不稳定(时快时慢、偶发超时甚至不可达) | 国际站(gitlab.com)同样可能不稳定;自托管不受影响 | 国内访问快且稳定 |
| 典型用法 | 开源项目、国际协作 | 企业内部一体化研发平台 | 国内团队、教学、个人项目 |
如实说明:国内访问 GitHub 的现实
在中国大陆访问
github.com可能出现:网页加载慢、git clone卡在Receiving objects、CI Runner 拉取超时、图片(头像/徽章)加载失败。这些是网络链路问题,不是账号或仓库问题。实务上的应对(按推荐度排序):
1. 代码走 SSH 而非 HTTPS,并配置
~/.ssh/config使用 443 端口的ssh.github.com;2. 配置 Git 代理(仅在你自己的合规网络环境下);
3. 用镜像或自建 GitLab(Gitee 导入、GitLab 自托管)在国内做日常开发,GitHub 只作为上游同步点;
4. CI 上优先用
actions/checkout等官方 Action(走 CDN),减少对源码站点的直接依赖。教学与团队内训场景,建议先确认网络可达性再选平台,否则「环境问题」会吃掉大半学习时间。
仓库结构规范
一个「看起来专业、新人能上手」的仓库,文件布局大致如下:
my-project/
├── README.md # 门面:是什么、怎么跑起来
├── LICENSE # 授权条款(不写 = 默认保留所有权利)
├── .gitignore # 忽略构建产物、依赖、密钥
├── .editorconfig # 跨编辑器基础风格(见 [[工具-06-编辑器与IDE]])
├── CONTRIBUTING.md # 怎么贡献:分支命名、提交规范、跑测试
├── CODE_OF_CONDUCT.md # 行为准则(开源项目建议有)
├── CHANGELOG.md # 版本变更记录
├── .github/
│ ├── PULL_REQUEST_TEMPLATE.md # PR 模板
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.yml # Bug 报告表单
│ │ ├── feature_request.yml # 功能请求表单
│ │ └── config.yml # 模板选择器配置
│ ├── CODEOWNERS # 谁负责哪些路径的评审
│ └── workflows/ci.yml # GitHub Actions 流水线
├── docs/ # 详细文档
├── src/ # 源码
└── tests/ # 测试
README 该写什么
README 是唯一「所有人都会看」的文件。推荐的六段结构:
# 项目名
一句话说明:这是一个用 XX 技术做的 YY,解决 ZZ 问题。

## 快速开始
git clone <repo-url>
cd my-project
npm install
npm run dev # 打开 http://localhost:5173
## 技术栈
- 前端:Vue 3 + TypeScript + Vite
- 后端:FastAPI + PostgreSQL
- 部署:Docker Compose
## 贡献方式
欢迎提交 Issue 与 PR,请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
## License
MIT © 2026 Your Name
要点:
- 一句话说明放最前面:读者 5 秒内决定要不要继续看;
- 截图/动图不可省:对前端与 GUI 项目,一张图胜过三段文字;
- 快速开始必须能直接复制粘贴成功:写完自己在一台干净机器上验证一遍;
- 技术栈写清版本:避免「我装的是 Java 8 为什么跑不起来」;
- 贡献方式给出明确入口:指向 CONTRIBUTING.md 与 Issue 模板。
LICENSE 选择
GitHub 官方文档说明:仓库没有 LICENSE 文件时,默认版权归作者所有,他人没有复制、分发、修改的权利(即使代码公开可见)。
| 许可证 | 类型 | 他人可商用 | 衍生作品必须开源 | 适用场景 |
|---|---|---|---|---|
| MIT | 宽松 | ✅ | ❌ | 最常用,最大化传播 |
| Apache-2.0 | 宽松 | ✅ | ❌(但有专利授权与变更声明要求) | 企业友好,含专利条款 |
| BSD-3-Clause | 宽松 | ✅ | ❌ | 与 MIT 类似 |
| MPL-2.0 | 弱著佐权 | ✅ | 仅修改的文件需开源 | 库,允许与闭源共存 |
| LGPL-3.0 | 弱著佐权 | ✅ | 库本身修改需开源 | 动态链接库 |
| GPL-3.0 | 强著佐权 | ✅ | ✅(整个衍生作品) | 追求软件自由 |
| AGPL-3.0 | 强著佐权 | ✅ | ✅(含网络服务) | 防止「SaaS 白嫖」 |
| Unlicense / CC0 | 放弃权利 | ✅ | ❌ | 公共领域 |
怎么选(务实版)
- 个人练手、教程代码、想让别人随便用 → MIT;
- 公司开源、担心专利 → Apache-2.0;
- 不想让云厂商闭源拿去卖 → AGPL-3.0;
- 学习笔记、文档、非代码内容 → CC BY 4.0 / CC BY-SA 4.0(知识共享协议,不是软件许可证)。
.gitignore
# ── 依赖 ──────────────────────────────
node_modules/
.venv/
venv/
__pycache__/
*.py[cod]
bin/
obj/
# ── 构建产物 ──────────────────────────
dist/
build/
*.dll
*.exe
.next/
coverage/
# ── 编辑器与系统 ──────────────────────
.vscode/*
!.vscode/settings.json # 团队共享的配置要保留
!.vscode/extensions.json
.idea/
.DS_Store
Thumbs.db
# ── 密钥与本地配置(最重要!)─────────
.env
.env.local
.env.*.local
*.pem
*.key
secrets.json
appsettings.Development.json
# ── 日志与运行数据 ────────────────────
*.log
logs/
*.sqlite3
.gitignore不是安全机制已经被
git add过的文件,之后再加进.gitignore不会让它从历史中消失。密钥一旦提交过,就等于已经泄露——处理方式见下文「常见事故与规避」。
CONTRIBUTING.md
告诉贡献者「怎么参与」,内容清单:
# 贡献指南
## 开发环境
1. 克隆仓库并安装依赖:`npm install`
2. 复制 `.env.example` 为 `.env` 并填入本地配置
3. 启动开发服务:`npm run dev`
## 提交前检查
- `npm run lint` 必须通过
- `npm run test` 必须全绿
- 提交信息遵循 Conventional Commits(`feat:`、`fix:`、`docs:`、`chore:`)
## 分支命名
- 功能:`feature/短描述`
- 修复:`fix/issue编号-短描述`
- 文档:`docs/短描述`
## Pull Request 要求
- 关联对应 Issue(`Closes #编号`)
- 单个 PR 控制在 400 行有效改动以内
- 附上验证方式与截图(UI 变更)
Issue 模板与 PR 模板的作用
| 模板 | 位置 | 作用 |
|---|---|---|
| Issue 模板 | .github/ISSUE_TEMPLATE/*.yml | 用表单强制收集关键信息(版本、复现步骤、日志),减少来回追问 |
| Issue 模板配置 | .github/ISSUE_TEMPLATE/config.yml | 关闭空白 Issue、把「使用问题」引导到讨论区 |
| PR 模板 | .github/PULL_REQUEST_TEMPLATE.md | 提醒作者填写「改了什么/为什么/怎么验证」,也用来自查 |
GitHub 的议题表单(issue forms)用 YAML 定义,支持文本、下拉、复选框、文件上传等字段类型:
# .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug 报告
description: 报告一个可复现的缺陷
title: "[Bug] "
labels: ["bug", "triage"]
body:
- type: markdown
attributes:
value: |
感谢反馈!请务必填写复现步骤与环境信息。
- type: textarea
id: steps
attributes:
label: 复现步骤
description: 请写出最小可复现步骤
placeholder: |
1. 打开首页
2. 点击「登录」
3. 输入错误的密码并提交
validations:
required: true
- type: textarea
id: expected
attributes:
label: 期望行为
validations:
required: true
- type: input
id: version
attributes:
label: 版本号
placeholder: v1.2.3
validations:
required: true
- type: dropdown
id: os
attributes:
label: 操作系统
options:
- Windows 11
- macOS
- Ubuntu 22.04
- 其他
validations:
required: true
- type: textarea
id: logs
attributes:
label: 相关日志
render: shell # 自动按 shell 语法高亮,作者不用加反引号
# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false # 关闭空白 Issue,强制走模板
contact_links:
- name: 使用问题请到 Discussions
url: https://docs.github.com/zh/discussions
about: 提问、交流用法请走讨论区,Issue 只用于缺陷与需求
PR 模板(.github/PULL_REQUEST_TEMPLATE.md):
## 改了什么
<!-- 一两句话说清变更内容 -->
## 为什么
<!-- 关联 Issue,说明动机 -->
Closes #
## 怎么验证
- [ ] 本地跑通 `npm run test`
- [ ] 手动验证步骤:1) … 2) …
## 截图(UI 变更必填)
<!-- 改动前 / 改动后 -->
## 自查清单
- [ ] 已自查 diff,无调试代码、无无关格式化
- [ ] 已补充/更新测试
- [ ] 已更新相关文档
分支策略对比
| 策略 | 结构 | 适用团队规模 | 发布节奏 | 复杂度 |
|---|---|---|---|---|
| Trunk-based(主干开发) | 只有 main + 生命周期 < 1 天的短分支 | 任意,尤其适合强 CI 团队 | 持续部署,随时可发 | 低 |
| GitHub Flow | main + 功能分支 + PR | 1~20 人,Web 服务 | 合并即部署 | 很低 |
| GitLab Flow | main + 环境分支(staging、production)或发布分支 | 10~100 人,需要环境隔离 | 按环境推进 | 中 |
| Git Flow | main + develop + feature/ + release/ + hotfix/* | 50 人以上,版本化交付 | 按版本发布(月/季度) | 高 |
GitHub Flow 的完整循环(官方文档描述):
1. 从 main 创建分支 git switch -c feature/login
2. 提交并推送 git push -u origin feature/login
3. 打开 Pull Request (可先开 Draft PR)
4. 讨论与评审 行内评论、CI 检查
5. 合并到 main Squash / Merge commit / Rebase
6. 删除分支 本地与远程都删
为什么小团队不该照搬 Git Flow:
develop分支是纯粹的成本:它引入了「两份主干」,任何合并冲突都要在develop和main之间同步两次;- 长生命周期分支 = 冲突制造机:
release/*存在两周,期间主干继续前进,最后合并时冲突量陡增; - 它解决的是「盒装软件多版本并行维护」的问题:需要同时维护 v1.2、v1.3、v2.0 三条线时才划算;
- 持续部署下没有「发布分支」的概念:Web 服务合并即上线,
release/*无事可做; - 认知负担:新人要记五种分支的命名与流向,而收益在小团队几乎为零。
选择建议
- 个人项目 / 学习仓库:GitHub Flow(
main+ 功能分支 + PR)足矣;- 小团队 Web 服务:GitHub Flow 或 trunk-based,配合必需 CI 检查与自动部署;
- 需要 staging 环境验收:GitLab Flow(
main→staging→production);- 有多个对外版本要维护(如 SDK、客户端):才考虑 Git Flow。
Pull Request / Merge Request 工作流
完整流程
# ── 1. 同步主干并创建分支 ────────────────────────────
git switch main
git pull --ff-only origin main
git switch -c feature/add-coupon
# ── 2. 小步提交 ─────────────────────────────────────
git add src/coupon.ts tests/coupon.test.ts
git commit -m "feat(coupon): 支持满减券叠加"
# ── 3. 推送并建立上游跟踪 ───────────────────────────
git push -u origin feature/add-coupon
# ── 4. 用 CLI 创建 PR(GitHub CLI)──────────────────
gh pr create \
--title "feat(coupon): 支持满减券叠加" \
--body "Closes #42" \
--reviewer alice,bob \
--label "enhancement"
# 想先建草稿(Draft PR):
gh pr create --draft --title "WIP: 优惠券叠加"
# ── 5. 评审期间保持同步(把 main 的更新合进来)──────
git switch main && git pull
git switch feature/add-coupon
git merge main # 或 git rebase main(见下文合并方式对比)
git push
# ── 6. 合并后清理 ───────────────────────────────────
gh pr merge --squash --delete-branch
git switch main && git pull
git branch -d feature/add-coupon # 若本地还留着
PR 描述该写什么
评审者拿到 PR 时,最先看到的是标题与描述。四要素缺一不可:
| 要素 | 回答的问题 | 反例 | 正例 |
|---|---|---|---|
| 改了什么 | 具体变更 | 「优化代码」 | 「优惠券计算支持多种券叠加,新增 CouponStack 类」 |
| 为什么 | 动机与背景 | (无) | 「Closes #42:用户反馈一单只能用一张券」 |
| 怎么验证 | 评审者如何确认 | 「测试过了」 | 「npm run test:coupon 全绿;手动:下单时选两张券,应看到 8 折」 |
| 截图/录屏 | UI 变更的效果 | (无) | 改动前后对比图 |
Draft PR 的用途
Draft PR(草稿拉取请求)是「已推送、想让人看见、但还没准备好被正式评审」的状态:
- 提前拿到方向反馈:架构方向错了,早说比晚说便宜;
- 让 CI 先跑起来:长测试可以在草稿阶段就开始跑;
- 团队可见性:别人知道你正在做这块,避免重复劳动;
- 不适合合并:Draft 状态无法合并(分支保护可要求必须先标记为 ready);
- 转为可评审:GitHub 上点「Ready for review」,GitLab 上把标题前缀
Draft:去掉。
gh pr ready # 把草稿标记为可评审
gh pr ready --undo # 再转回草稿
关联 Issue 的语法
在 PR 描述或提交信息里写关键词 + Issue 编号,合并后自动关闭该 Issue:
| 语法 | 效果 |
|---|---|
Closes #12 | 合并时关闭 #12 |
Fixes #12 | 同上 |
Resolves #12 | 同上 |
Closes #12, closes #13 | 一次关多个 |
Refs #12 / Related to #12 | 只引用不关闭(推荐用于「部分实现」) |
Closes owner/repo#12 | 关闭其他仓库的 Issue |
别在无关 PR 里写
Closes一个 PR 关闭十个 Issue,看起来效率很高,实际上破坏了追溯性:出了问题无法判断是哪个变更引入的。一个 PR 对应一个逻辑变更、通常对应一个 Issue。
Review 的三种结果与处理
GitHub 的评审结论有三种:
| 结果 | 含义 | 作者应做什么 |
|---|---|---|
| Comment(评论) | 只留意见,不表态 | 逐条回应;若对方未明确要求改动,判断是否需要改 |
| Approve(批准) | 认可,可以合并 | 等必需的批准数达标 + CI 绿 → 合并 |
| Request changes(请求修改) | 有问题,阻塞合并 | 必须处理;处理完请求重新评审(re-request review) |
处理流程建议:
- 收到
Request changes:先逐条回复(「已改」「同意,已改」「我想讨论一下:…」),不要批量「改了」了事; - 改动后推送到同一分支,PR 会自动更新;不要关掉 PR 重开(会丢失讨论历史);
- 用
gh pr review --approve或网页上的按钮请求复审; - 如果某条意见你不打算改,必须说明理由并达成一致,不要默默忽略后合并。
三种合并方式对比
GitHub 官方文档对三种策略的定位:
| 方式 | 结果历史 | 何时选择 | 注意 |
|---|---|---|---|
| Create a merge commit(合并提交) | 保留 PR 分支的每一个提交,额外加一个合并点 | 团队重视完整历史,或分支上每个提交本身有意义(如含独立重构) | 历史呈网状,git log 较吵;本地等价于 git merge --no-ff |
| Squash and merge(压缩合并) | 把 PR 的所有提交压成主干上的一个提交 | PR 代表一个逻辑变更,尤其含大量「修改」「再修一下」的小提交 | 中间提交不保留;不适合长生命周期分支(后续 PR 会包含已压缩的提交,冲突概率上升) |
| Rebase and merge(变基合并) | 把 PR 的提交逐个重放到主干,不产生合并提交,历史线性 | 团队要线性历史,且分支上的提交已整理干净(已 squash 过自己的 WIP) | 会重写提交 SHA;GitHub 上会删掉「空提交」(--allow-empty 创建的那种),与本地 git rebase 略有差异 |
选择原则(实用版):
问三个问题:
1. 你们需要「按 PR 粒度回滚」吗? → 是:Squash(一个 PR = 一个可回滚提交)
2. 你们需要 bisect 精确定位到小提交吗? → 是:Rebase 或 Merge commit
3. 分支上是否有「必须保留」的独立提交? → 是:Merge commit
90% 的团队最优解:Squash and merge
- 主干历史一条线:feat: xxx / fix: yyy / docs: zzz
- 每个提交都可独立回滚
- 作者在分支上可以随便提交「wip」「fix typo」
合并后删分支
# 网页上合并时勾选「Delete branch」(推荐,最省心)
# CLI :
gh pr merge --squash --delete-branch
# 本地清理已合并的本地分支
git branch -d feature/add-coupon
# 顺手清理「远程已删但本地仍跟踪」的分支引用
git fetch --prune
为什么必须删
分支列表是团队的「当前工作视图」。留着几十个已合并分支,
git branch -a就没法用了,也没人敢批量清理——因为无法一眼看出哪些还有用。
Code Review 方法论
评审者该关注什么
按重要性排序:
| 优先级 | 关注点 | 具体检查 |
|---|---|---|
| 1 | 正确性 | 逻辑是否满足需求?有没有反了的条件(> vs >=)? |
| 2 | 边界与异常 | 空值、空集合、0、负数、超大值、并发、超时、失败分支 |
| 3 | 安全性 | 输入校验、SQL 拼接、越权(水平/垂直)、密钥硬编码、日志泄露敏感数据 |
| 4 | 测试覆盖 | 新增逻辑有没有对应测试?测试断言是否足够强? |
| 5 | 可读性 | 命名是否表意?函数是否过长?嵌套是否过深?有没有「聪明但难懂」的技巧 |
| 6 | 架构一致性 | 是否复用了已有抽象?有没有引入重复逻辑(DRY)?层次是否被穿透 |
| 7 | 性能 | 循环内查询(N+1)、无界集合驻留内存、无索引的查询 |
| 8 | 可维护性 | 是否有必要的注释解释「为什么」?错误信息是否可诊断 |
不该纠结什么
个人风格偏好一律交给自动化工具,人力只用在工具看不到的地方:
| 不要评论 | 交给谁 |
|---|---|
| 缩进、分号、引号、行宽 | Prettier(见 [[工具-03-包管理器]]、[[前端-09-前端工程化与调试]]) |
| 命名 casing、未使用变量、简单的可疑写法 | ESLint / Ruff / 编译器警告 |
| import 排序 | ESLint import/order 等规则 |
| 文件末尾换行、行尾符 | .editorconfig |
| 「我喜欢用 A 而不是 B」(无客观差异) | 不评论 |
一条硬标准
如果一条评论可以被工具自动检查,就不该由人提。人提这类意见的边际价值接近零,且会让作者觉得被挑刺。
如何给建设性评论
三条原则:
- 对事不对人:说「这个函数在并发下会读到脏数据」,不说「你没考虑并发」;
- 区分「必须改」与「建议」:用前缀标记(团队约定俗成即可):
[blocking] 这里会 SQL 注入,必须用参数化查询。
[suggestion] 可以考虑把这个判断抽成函数,非必须。
[nit] 变量名 typo:recieve → receive。(不阻塞)
[question] 这里为什么用 Redis 而不是本地缓存?想了解背景。
[praise] 这个边界处理很细,学到了。
- 用提问代替命令:
「这里如果 items 为空会怎样?」比「你没处理空数组」更容易被接受,也给对方解释的余地(也许上游已保证非空)。
评论要给出可执行的改法或明确的判断依据:
❌ 这个写法不好。
✅ 这里每次循环都查一次数据库,100 个商品就是 100 次查询(N+1)。
建议先批量查出来再在内存里 map,参考 UserService.listWithRoles 的写法。
作者如何回应
| 做法 | 说明 |
|---|---|
| 不辩护 | 被指出问题时,第一反应是「确实」,而不是「因为当时…」。理由可以补充,但先承认问题 |
| 逐条回应 | 每条评论都回复:已改(commit abc1234) / 同意,但我建议单独开 PR / 我理解你的顾虑,但这里是刻意的,因为… |
| 有分歧就拉同步沟通 | 评论区来回超过 3 轮仍未达成一致 → 拉个 15 分钟语音。文字沟通在多轮后成本指数上升 |
| 不要默默改掉再合并 | 评论线程不回复会让评审者不知道你是否看到了 |
| 推动 PR 前进 | 主动 @ 评审者、设置截止时间。PR 挂着不开工是团队吞吐量的最大杀手 |
| 接受「不完美的合并」 | 如果意见属于「可以更好但不必现在做」,主动建一个 follow-up Issue,而不是让 PR 无限期挂着 |
小 PR 原则
GitHub 官方文档明确建议写小而聚焦的 PR:更容易审查、更安全地合并,也更容易让评审者理解意图、更快发现问题。
为什么 200~400 行是评审质量的分水岭:
- 评审是注意力有限的活动。研究表明评审者在单次评审超过约 400 行后,缺陷发现率显著下降;
- 大 PR 里,重要改动会被无关的格式化、重命名淹没;
- 大 PR 的评论区会变成「多线程聊天」,作者容易漏掉意见;
- 大 PR 一旦方向错了,回退成本极高。
拆分方法:
| 拆法 | 做法 | 示例 |
|---|---|---|
| 按层次 | 一个 PR 只动一层:数据库 → 服务 → API → 前端 | PR1: 加表与迁移;PR2: 服务层逻辑;PR3: 暴露 API;PR4: 前端接入 |
| 按功能 | 一个 PR 只交付一个可独立描述的能力 | 「支持优惠券」拆成「创建券」「应用券」「券列表页」 |
| 先重构后加功能 | 第一个 PR 只做无行为变化的重构(测试全绿即安全),第二个 PR 加功能 | PR1: 抽 PriceCalculator;PR2: 在它里面加折扣逻辑 |
| 按机械改动分离 | 格式化、重命名、依赖升级单独成 PR | PR: chore: prettier 全仓库格式化 |
拆分不等于碎片化
每个拆出来的 PR 应能独立通过 CI 与评审,并且合并后系统仍是可工作的(可用 feature flag 隐藏未完成功能)。
自动化介入
分支保护规则
在 GitHub 上,受保护分支(protected branch)可以强制以下规则:
| 规则 | 作用 |
|---|---|
| Require a pull request before merging | 禁止直接推送,必须走 PR |
| Require approvals(N 人) | 至少 N 个批准才能合并 |
| Dismiss stale approvals | 有新推送时,旧批准自动失效(很关键,防止「批准后再偷改」) |
| Require review from Code Owners | 改到某目录必须由该目录负责人批准 |
| Require status checks to pass | CI 必须绿(可指定具体检查项) |
| Require branches to be up to date | 合并前必须先同步主干(避免「绿的是旧基线的组合」) |
| Require conversation resolution | 所有评论线程必须标记已解决 |
| Require linear history | 禁止合并提交(强制 squash 或 rebase) |
| Require signed commits | 提交必须签名 |
| Restrict who can push | 只有指定人或团队能推 |
| Do not allow bypassing | 连管理员也不能绕过(强烈建议开启) |
CODEOWNERS
CODEOWNERS 文件声明「哪些路径由谁负责」,配合「Require review from Code Owners」实现自动指派评审人:
# .github/CODEOWNERS
# 语法:路径模式 负责人(用户或 @组织/团队)
# 默认:所有文件由核心团队负责
* @myorg/core
# 前端
/frontend/ @myorg/frontend-team
*.vue @myorg/frontend-team
*.tsx @myorg/frontend-team
# 后端与基础设施
/backend/ @myorg/backend-team
/infra/ @myorg/devops
Dockerfile @myorg/devops
*.tf @myorg/devops
# 安全敏感路径:必须由安全组评审
/auth/ @myorg/security
/src/crypto/ @myorg/security
*.pem @myorg/security
# 文档
/docs/ @alice @bob
规则要点:
- 路径模式支持
*、**、?等通配; - 最后匹配的规则生效(与
.gitignore相反),所以默认规则*要写在最前面; - 团队用
@org/team-name,个人用@username; - 文件可放在
.github/、仓库根目录或docs/下。
让自动化成为「守门人」而不是「保姆」
# .github/workflows/ci.yml —— PR 上的必跑检查(示意)
name: CI
on:
pull_request:
branches: [main]
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run lint # 风格问题由工具拦,不进 Code Review
- run: npm run typecheck
- run: npm run test:unit -- --coverage
- run: npm run build
深入 CI 配置
流水线语法、矩阵构建、缓存、制品与部署策略见 工具-08-CICD入门。此处只强调一点:凡是能自动检查的,都不要靠人。
Issue 管理
Issue 与 PR 的分工
| Issue | Pull Request | |
|---|---|---|
| 表达 | 「有什么问题 / 想要什么」 | 「我这样改了」 |
| 状态 | Open → Closed | Open → Draft → Merged / Closed |
| 内容 | 描述、复现、讨论、方案权衡 | diff、CI 结果、行内评审 |
| 关闭方式 | 手动,或被 PR 的关键词自动关闭 | 合并即关闭(未合并关闭需说明原因) |
| 数量关系 | 一个 Issue 可由多个 PR 完成 | 一个 PR 通常对应一个 Issue |
常见反模式
- 用 Issue 当聊天室:一个问题拆成几十条评论讨论方案,没有结论。应把结论沉淀回 Issue 描述或转成设计文档。
- PR 里夹带未讨论的大改动:「顺便重构了整个模块」——评审者无法有效评估,正确做法是拆 PR 或先开 Issue 讨论。
- Issue 长期无人处理也不关闭:定期 triage(分类)是维护者的核心工作。
标签体系
用三个维度组织标签,避免「标签爆炸」(几十个含义重叠的标签等于没有标签):
| 维度 | 标签 | 说明 |
|---|---|---|
| type(类型) | type/bug、type/feature、type/docs、type/refactor、type/chore | 这是什么性质的变更 |
| priority(优先级) | priority/p0(立刻)、p1(本迭代)、p2(计划内)、p3(有空再说) | 多紧急 |
| status(状态) | status/triage、status/confirmed、status/in-progress、status/blocked、status/needs-info | 现在处于什么环节 |
| 辅助 | good first issue、help wanted、duplicate、wontfix、question | 面向社区协作 |
good first issue的价值给新贡献者准备一批「范围明确、有指引、不需要深入架构」的任务,是开源项目最有效的留存手段。第一次贡献成功的人,第二次贡献的概率高得多。
里程碑与看板
- 里程碑(Milestone):把一组 Issue 绑定到一个目标(如
v2.0或「十月迭代」),可查看完成百分比与剩余时间; - 看板(Project / Board):把 Issue 按状态列(Todo / In Progress / Review / Done)展示,用于每日站会同步;
- 使用纪律:看板列必须少(3~5 列),WIP(进行中)设上限,否则看板会退化成「一堆卡片」;
- GitHub Projects 支持自定义字段与自动化规则(如「PR 关联后自动移到 Review」),GitLab 侧对应 Issue Board 与 Epic。
可复现 Bug 报告模板
一个高质量的 Bug 报告必须让维护者不追问就能复现:
## 环境
- 版本:v1.4.2(`git rev-parse HEAD` 输出:a1b2c3d)
- 操作系统:Windows 11 23H2
- 浏览器/运行时:Chrome 130 / Node 22.11.0
- 数据库:PostgreSQL 16.1
## 复现步骤
1. 以普通用户登录
2. 打开「我的订单」页
3. 点击第二页
4. 观察结果
## 期望行为
显示第 11~20 条订单。
## 实际行为
显示第 1~10 条订单(页码高亮在「2」)。
## 复现频率
100%(5 次尝试 5 次复现)
## 最小复现
(可选但极有价值)一个最小仓库或 CodePen 链接:
https://example.com/minimal-repro
## 日志 / 报错
TypeError: Cannot read properties of undefined (reading 'slice')
at OrdersList.vue:42
## 补充信息
- 第 1 页正常,第 3 页及以后也正常,只有第 2 页异常
- 已尝试清除缓存,无效
开源协作礼仪
| 场景 | 该做 | 不该做 |
|---|---|---|
| 提问前 | 先搜 Issue、Discussions、文档;(很多问题已被回答过十次) | 直接开新 Issue 问「怎么用」 |
| 提 Bug | 给最小可复现示例(Minimal Reproducible Example),附版本与日志 | 只写「不工作了」「有 bug」;贴几百行无关代码 |
| 提问措辞 | 描述事实与已尝试的方案;给出自己排查的结论 | 「你们这个项目怎么这么烂」;命令式要求 |
| 等待回复 | 维护者多为无偿业余时间工作,等 3~7 天正常 | 24 小时内 @ 三次、连发催促、私信轰炸 |
| 提第一个 PR | 从修文档、改 typo、补测试、处理 good first issue 开始 | 一上来提「重写核心架构」这种巨型 PR |
| 被拒绝 | 询问理由、接受 wontfix;可用于自己的 fork | 反复争辩、发长文控诉、开小号重提 |
| 被合并 | 说句谢谢;按项目规范更新文档 | 提交后消失,不响应后续评审意见 |
一条底层原则
开源协作是陌生人之间的自愿合作。你的 Issue/PR 是「请求」而非「要求」;你的目标是降低对方处理你的问题的成本——最小复现示例、清晰的标题、完整的模板,都是在替对方省时间。
常见事故与规避
事故一:误提交密钥
错误处理(很多人的第一反应):
# ❌ 只删文件 + 提交 —— 密钥仍在历史里,任何人 clone 都能翻出来
git rm .env
git commit -m "remove env file"
git push
正确认知:只要密钥进过远程仓库,就视为已泄露。原因:
- 历史提交永久保留(除非重写历史);
- 可能已被 fork、已被 CI 日志记录、已被镜像站抓取、已被爬虫扫描(GitHub 上的公开仓库密钥常在数分钟内被自动扫描并尝试利用);
- 删除提交无法撤回已经发生的泄露。
正确处置顺序(顺序不可颠倒):
1. 【立刻轮换/吊销密钥】 ← 最重要,永远先做这一步
- 云厂商控制台:禁用/删除该 AccessKey,生成新密钥
- 数据库:改密码并踢掉现有连接
- 第三方 API:在服务商后台 revoke 旧 Token
- 证书/私钥:重新签发,旧的加入吊销列表(CRL)
2. 【评估影响面】查看访问日志:有没有被使用过?动了哪些资源?
3. 【清理仓库】
- 未推送过:git reset / git commit --amend 即可
- 已推送但只有你自己在开发:用 git filter-repo 重写历史后强推
- 已推送且有多人协作:通知所有人,约定时间统一处理(否则历史会互相"复活")
- 联系平台支持:GitHub 支持请求清除缓存的提交
4. 【建立防线】
- CI 加密钥扫描(GitHub 的 secret scanning、gitleaks、trufflehog)
- .env.example 代替 .env 提供模板
- 用平台 Secrets / Vault 管理生产密钥(见 [[后端-08-部署与运维基础]])
- 开启推送保护(push protection)阻止含密钥的推送
顺序错了等于没做
「先删提交再换密钥」是最危险的错误顺序:你以为处理完了,实际泄露仍在持续,而你不再警惕。
事故二:强推公共分支
git push --force 会把远程分支重写为本地状态,丢弃远程上已有的提交。如果别人已经基于那些提交工作了:
- 他们的本地分支与远程分叉,下次
git pull会得到一团混乱; - 他们推上来的提交凭空消失(在 reflog 过期后);
- 更糟的是:别人一 push,你删掉的提交又回来了(因为他们本地还有),历史来回摆荡。
--force 与 --force-with-lease 的区别
| 命令 | 行为 | 安全性 |
|---|---|---|
git push --force / -f | 无条件用本地覆盖远程 | ❌ 会覆盖任何远程更新,包括你尚未拉取的他人提交 |
git push --force-with-lease | 仅当远程分支仍等于你上次拉取时的状态才允许覆盖 | ✅ 若期间有人推送过,直接拒绝,保护他人的提交 |
git push --force-if-includes | 在 --force-with-lease 基础上再确认「要覆盖的提交确实是我本地已包含的」 | ✅✅ 最严格 |
# 场景:你 rebase 了自己的功能分支,需要更新远程
git switch feature/my-work
git fetch origin
git rebase origin/main
# ❌ 危险
git push --force
# ✅ 安全(别人若在此期间推过东西,会被拒绝,你就知道要先 fetch)
git push --force-with-lease
# 更严格
git push --force-with-lease --force-if-includes
规则:
- **绝不对
main/master/develop/release/*强推**。这些分支应开启分支保护(禁止强推与删除); - 只对自己独占的功能分支强推;
- 即使在功能分支上,也用
--force-with-lease而不用--force; - 团队约定:推送前先
git fetch,否则 lease 的保护对象是你过期的认知。
配置成默认行为
```bash
git config --global alias.pushf "push --force-with-lease"
# 或直接改默认:让 --force 也带上 lease 语义
git config --global push.useForceIfIncludes true
```
相关 Git 原理(reflog、rebase、revert 与 reset 的区别)见 工具-01-Git版本控制。
怎么用
完整配置文件
CONTRIBUTING.md(可直接改用)
# 贡献指南
感谢你有兴趣为本项目做贡献!
## 报告问题
请使用 [Issue 模板](../../issues/new/choose)。**不要**在 Issue 中粘贴密钥、token 或真实用户数据。
## 开发环境搭建
git clone <repo-url> && cd <repo>
npm install
cp .env.example .env
npm run dev
## 分支与提交规范
- 从 `main` 切出分支:`feature/<简述>`、`fix/<issue号>-<简述>`、`docs/<简述>`
- 提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/):
`feat:` `fix:` `docs:` `refactor:` `test:` `chore:`
## 提交 PR 前
npm run lint && npm run typecheck && npm run test
- PR 请关联 Issue:在描述中写 `Closes #<编号>`
- 一个 PR 只做一件事,有效改动建议不超过 400 行
- UI 变更请附截图
## 行为准则
参与本项目即表示同意遵守 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
.github/PULL_REQUEST_TEMPLATE.md
## 改了什么
<!-- 一句话概括 -->
## 为什么
Closes #
## 怎么验证
- [ ] `npm run test` 全绿
- [ ] 手动验证:
1.
2.
## 截图 / 录屏(UI 变更必填)
改动前 改动后
## 自查
- [ ] 看过自己的完整 diff,无调试残留、无无关格式化
- [ ] 新增逻辑有对应测试(边界与异常已覆盖)
- [ ] 已更新相关文档 / CHANGELOG
- [ ] 无密钥、token、真实用户数据被提交
.github/CODEOWNERS
# 默认负责人(必须放最前,最后匹配的规则生效)
* @myorg/maintainers
/src/api/ @myorg/backend
/src/web/ @myorg/frontend
/src/auth/ @myorg/security
/infra/ @myorg/devops
/docs/ @alice
*.md @alice
.github/workflows/ @myorg/devops
.gitignore(Python + Node 混合项目)
# Python
__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/
.mypy_cache/
.ruff_cache/
*.egg-info/
# Node
node_modules/
dist/
build/
coverage/
.vitest/
*.tsbuildinfo
# 环境与密钥
.env
.env.*
!.env.example
*.pem
*.key
secrets/
# 编辑器
.vscode/*
!.vscode/settings.json
!.vscode/extensions.json
.idea/
# 系统
.DS_Store
Thumbs.db
# 日志
*.log
logs/
.github/workflows/ci.yml(PR 守门)
name: CI
on:
pull_request:
branches: [main]
push:
branches: [main]
concurrency: # 同一 PR 的新推送取消旧运行,省额度
group: ci-${{ github.ref }}
cancel-in-progress: true
jobs:
check:
runs-on: ubuntu-latest
permissions:
contents: read # 最小权限原则
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # 需要 diff 覆盖率时用 0
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- name: Lint(风格问题在工具层拦掉)
run: npm run lint
- name: Type check
run: npm run typecheck
- name: Unit tests + coverage
run: npm run test:unit -- --coverage
- name: Build
run: npm run build
secret-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: 扫描提交历史中的密钥
run: |
docker run --rm -v "$PWD:/p" zricethezav/gitleaks:latest \
detect --source=/p --verbose --no-git=false
流水线语法细节
on/jobs/needs/ 矩阵与缓存策略见 工具-08-CICD入门;此处关注的是「哪些检查必须挡在合并之前」。
可执行命令清单
# ── 认证与首次配置 ────────────────────────────────────
gh auth login # GitHub CLI 登录
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.ff only # 拉取只允许快进,避免产生意外合并提交
# SSH 走 443 端口(网络受限环境的常用解法)
cat >> ~/.ssh/config <<'EOF'
Host github.com
HostName ssh.github.com
Port 443
User git
EOF
ssh -T git@github.com # 验证连通性
# ── 日常 PR 流程 ──────────────────────────────────────
git switch -c feature/coupon
git add -p # 分块暂存,便于原子提交
git commit -m "feat(coupon): 支持满减券叠加"
git push -u origin feature/coupon
gh pr create --fill # 用提交信息填充标题与描述
gh pr create --draft --title "WIP: 券叠加"
gh pr list --state open --author "@me"
gh pr view --web
gh pr checks # 查看 CI 状态
gh pr diff # 在终端看 diff
# ── 评审 ─────────────────────────────────────────────
gh pr review 12 --approve
gh pr review 12 --request-changes --body "金额边界未处理,见评论"
gh pr review 12 --comment --body "几个建议,不阻塞合并"
gh pr ready # 草稿转可评审
gh pr checkout 12 # 把别人的 PR 拉到本地试跑
# ── 合并与清理 ───────────────────────────────────────
gh pr merge 12 --squash --delete-branch # 最常用
gh pr merge 12 --merge --delete-branch # 保留完整历史
gh pr merge 12 --rebase --delete-branch # 线性历史
gh pr close 12 # 不合并,关闭
git fetch --prune # 清理已删除的远程分支引用
# ── Issue ────────────────────────────────────────────
gh issue create --title "[Bug] 分页第2页数据错误" --label "type/bug,priority/p1"
gh issue list --label "good first issue" --state open
gh issue comment 42 --body "已定位到 OrdersList.vue:42"
gh issue close 42 --reason "completed"
# ── 安全相关 ─────────────────────────────────────────
git push --force-with-lease # 只对自己的分支用
git log --all --full-history -- "*.env" # 检查历史中是否出现过 .env
gitleaks detect --source . --verbose # 本地扫描密钥(需先安装)
常见坑
高频错误清单
1. 在
main上直接开发:哪怕只有你一个人,也养成切分支的习惯——否则你永远无法为一个「顺手的小改动」单独开 PR。2. PR 里混入格式化改动:
prettier全量格式化会把真正的逻辑改动淹没在几千行 diff 里。格式化单独成 PR。3. 不拉取主干就开 PR:基于一周前的
main开发,合并时冲突一堆。开始前先git pull --ff-only。4. 合并后不删分支:分支列表变成垃圾场。
5. 用
Closes关掉不相关的 Issue:破坏追溯性。6. 评审只写「LGTM」:要么真的看过并说明看了什么,要么不批准。
7. 批准后又偷偷推送:开启「Dismiss stale approvals」防止这种情况。
8. 把密钥写进
.env.example:模板文件是要提交的,只放占位值(API_KEY=your-key-here)。9. Issue 描述里贴生产日志:可能含用户隐私、内部 IP、token。先脱敏。
10. 对公共分支用
--force:见上文,等于删别人的工作。
练习题
- 分支策略选择:一个 6 人团队做 B 端 SaaS,每周发布一次,有 staging 验收环境。他们现在用 Git Flow,
develop与main频繁冲突。请给出一个更合适的策略,并说明迁移步骤与风险。
- 拆 PR:你接到的任务是「支持优惠券功能」,涉及:新增
coupons表与迁移脚本、CouponService、POST /coupons/apply接口、结算页选择券的 UI、管理后台建券页面。请把它拆成 3~5 个可独立评审、独立通过 CI 的 PR,并写出每个 PR 的标题与一句话描述。
- Code Review 演练:以下评论有什么问题?请改写成建设性版本。
> 「这里你怎么不用 Map?List 查询是 O(n),性能肯定有问题。改一下。」
写出改写后的评论,并说明你会在什么情况下同意原评论的判断。
- 密钥泄露处置:同事在周五下午误把一个 AWS AccessKey 推到了公司私有仓库的
main分支(仓库有 20 人协作)。请按时间顺序列出你的处置步骤,并指出哪一步最容易被做错。
- 合并方式选择:项目要求「主干历史一行一个功能、可按功能回滚、能用
git bisect定位到具体功能但不能定位到功能内部的小提交」。请选择合并方式并说明取舍。若后来团队要求「bisect 必须能定位到功能内部的每个小提交」,需要改变什么前提?
FAQ
GitHub 和 GitLab 到底选哪个?
看三个约束:(1) 网络——国内团队若无法稳定访问
github.com,企业内部协作优先自托管 GitLab 或 Gitee;(2) 是否需要一体化——GitLab 内置 CI、制品库、安全扫描、环境与审批,开箱即用程度更高;GitHub 的生态更大(Actions 市场、社区、开源项目基数);(3) 是否开源/面向社区——开源项目几乎都以 GitHub 为主场,贡献者规模不可比。个人学习建议:代码放 GitHub 练协作,同时会一点 GitLab CI,两者概念高度对应。
小团队真的需要 PR 流程吗?两个人直接推主干不行吗?
「两个人」的场景下,PR 的价值主要不是评审(你们彼此信任),而是:(1) CI 的门禁——PR 上跑测试,绿了才能合,避免把主干搞坏;(2) 变更记录——半年后能查到这行代码为什么改;(3) 回滚粒度——一个功能一个提交。成本很低(多几次点击),收益长期复利。可以省掉「必须有人批准」,但不建议省掉「必须走 PR + 必须 CI 绿」。
Code Review 时同事总挑格式问题,怎么处理?
用工具消灭这类讨论:接入 Prettier / ESLint / Ruff,配 pre-commit 钩子在提交前自动修复,CI 里加
--check模式。然后在团队内明确一条规则:「凡工具能检查的,不在评审里提」。如果对方仍坚持个人偏好,把它写进.editorconfig或 lint 规则里,让规则说话,而不是让资深的人说话。
我的 PR 挂了一周没人评审怎么办?
按顺序做:(1) 确认 PR 小且描述清晰(大 PR 天然被拖延);(2) 在 PR 里 @ 具体的人(
@alice 这个改动涉及你负责的支付模块,方便时看一下),而不是发在群里;(3) 主动约 15 分钟同步过一遍(很多「没时间评审」其实是「不知从哪看起」);(4) 找团队确认评审 SLA(如「24 小时内给出首次反馈」)并写进 CONTRIBUTING;(5) 若长期无人评审,说明流程本身有问题——把它提到团队会议,而不是默默继续堆 PR。
相关笔记
- 工具-01-Git版本控制:分支、合并、变基、冲突解决、reflog 找回误删提交。
- 工具-08-CICD入门:GitHub Actions 语法、流水线设计、分支保护如何与 CI 配合。
- 工具-02-命令行与Shell:GitHub CLI(
gh)与 Git 命令行效率技巧。 - 后端-08-部署与运维基础:Secrets 管理、环境变量、灰度发布与回滚。
- 前端-09-前端工程化与调试:Prettier / ESLint 落地,让风格问题离开评审。
- 常见问题FAQ:跨方向的协作与工具类常见疑问。
参考来源
- GitHub Docs(中文)— GitHub Flow(分支 → 提交 → PR → 评审 → 合并 → 删除的完整循环)
- GitHub Docs(中文)— 合并拉取请求(合并提交 / 压缩合并 / 变基合并三种策略的官方对照与选择建议、压缩合并不适合长生命周期分支的说明)
- GitHub Docs(中文)— 创建拉取请求(创建流程、Draft PR、
gh pr create各参数、关联 Issue 的用法) - GitHub Docs(中文)— 帮助他人评审你的更改(官方对「写小型 PR」「提供上下文」「先自查自己的 PR」的建议)
- GitHub Docs(中文)— 关于仓库 README 文件(README 的作用与位置)
- GitHub Docs(中文)— 为仓库颁发许可证(无 LICENSE 时的默认权利状态、许可证选择入口)
- GitHub Docs(中文)— 关于代码所有者(CODEOWNERS 语法与生效规则)
- GitHub Docs(中文)— 关于受保护分支(必需评审、必需状态检查、禁止强推等规则)
- GitHub Docs(中文)— 为存储库配置议题模板(议题表单 YAML 语法、
config.yml、模板排序) - GitLab Docs — Merge requests(MR 的 Assignee/Reviewer 角色、审批规则、关闭 Issue 的语法、源分支删除行为)
关于链接与访问
上述 GitHub 文档均使用
docs.github.com域名(含中文页面),未引用github.com路径。中国大陆访问 GitHub 服务可能不稳定,如遇打不开,可先用docs.gitlab.com的对应章节(MR 与分支保护概念基本一一对应)。