协作流程

使用修改版的 git-flow 流程 作为 Git 库的协作流程

需要修改的原因是企业场景下任何对中心库的修改必须有第二个人 review 并审批通过，在公司内则体现为任何变更都以提 PR 形式进行，而原版 git-flow 没有考虑这一点（原版的使用方法为本地操作后直接 push）

与原版 git-flow 流程的差异如下

  • feature 分支的命名应当符合 feature/xxx 的格式。feature 分支仅用于在中心库暂存（stage）技术上非平滑迁移的功能，主要是必须变更表结构的大功能一类。这类分支往往开发周期也较长，且不能 block 日常小修小补（往往业务上也不会允许发现问题不马上修复）
  • 如涉及中心库的分支增减、含义变化等变更操作，应当在团队内同步
  • 个人库的分支命名不作强制要求，但建议使用或体现 issue 号
  • 不开 release/xxx 分支，代之以直接提发版 PR
  • 每次发版后不需要马上打 tag 并做 master -> develop 的合并，主要原因是累（原版自动化的动作，在公司场景下要手动操作）。但仍然建议 tag 及时或隔一阵批量打，建议时常做 master -> develop 的操作
  • HOTFIX 的场景不受影响，仍然必须 master -> develop
  • 版本 tag 应当打到发版 PR 的合并提交上
  • master -> develop 的操作也采用提 PR 的形式进行

额外说明

  • 禁止在中心库直接进行研发工作。请在本人的 fork 进行工作并通过 PR 与中心库交互。建议单开分支，不要直接使用默认分支（如 develop）
  • 除特殊场合外（开 feature 分支、修复他人误操作等），禁止直接向中心库做 push 操作
  • 在美国、欧洲等地，由于 BLM 运动等政治正确原因，现已存在将 master 分支重命名为 main 的实践。由于中国技术人员一般理解的 master 并不含种族歧视意味，且该变更对研发实质上无影响，故不跟进

Pull Request

一个 Pull Request（下称 PR）一般应当只对应一个 issue

为使团队成员间的工作进度分享透明化，协作高效、规范化，提倡遵循社区最佳实践。建议早提 PR（带 [WIP] 标签避免他人提前看到施工现场），频繁 push，经常 rebase，提交 review 前整理 commit 内容与顺序等

PR 标题

PR 标题必须包含其实现的 issue 编号

如果当前做的事情暂无 issue，必须建立一个，这主要是允许各团队成员正确追踪工作量。QA 性质的工作一视同仁，也必须建立相应的 issue

如 PR 同时实现了多个 issues，标题必须包含每一个 issue 编号

PR 标题可以带 0 或多个固定格式的前缀，用来传达固定含义。允许的前缀及其含义如下

前缀 含义 备注
[WIP] 施工中（Work in Progress） 一般情况下其他人应当无视该 PR 的存在，包括但不限于无视其不符合规范、代码脏乱差、测试失败等问题。禁止被合并
[QA] 正常由 QA 发起的工作 行有余力的研发同学可以辅助部分 QA 工作，这部分工作虽然由研发同学发起，性质仍然属于 QA 工作，因此也要带上该前缀
[DO NOT MERGE] 并不预期被合并的代码 一般用于肯定不会合并的临时调试性代码，例如单纯只为加两行日志发到测试环境之类。其他人也应当无视该 PR 的存在。禁止被合并

PR 标题中的每个前缀与每个 issue 号之间必须使用 1 个半角空格分隔，最后一个 issue 号与 PR 标题之间也必须使用 1 个半角空格分隔。作为 PR 标题的句子末尾禁止带标点

HOTFIX PR 的标题必须以 HOTFIX 字样开头（除前缀、issue 号之外），禁止在 HOTFIX 字样后带标点

特别地，对于协作流程所使用的特殊 PR，标题不采用上述的形式，而必须采用以下的固定写法（不区分大小写）

标题 含义
master -> develop 用于 HOTFIX 或正常发布后的往回合并

PR 标题应当表明做的具体事情。虽然复制粘贴 issue 标题是允许的，但如果相应 issue 的标题描述不具体，则不建议这么做

PR 正文（description）

选填。PR 的正文如果填写，主要用来记录辅助 review 的内容，例如施工进度、review comments 订正进度、依赖的其他 PR、相关 commit hash 等等

如需要附着大段说明文字，此时这些文字往往具有业务性质，应当写在 JIRA issue 正文、JIRA issue 评论区、CF 文档等位置。这是由于非研发人员如 PM 没有代码托管平台的权限，但往往也有阅读相关细节的需求

建议善用 GitHub 的自动关联功能，将相关的其他 PR 一并提及

Commit

变更的分拆原则（价值观）

研发人员应当尽力对单个 PR 所含的 commits 进行合理分拆

每个 commit 应当含且仅含 1 个逻辑变更

每个 commit 均应当能在被作为 HEAD 检出的情况下正常编译、运行。这是为了万一出现知识失传等情况，方便未来的开发人员在不熟悉项目的前提下对任意时间点的系统进行阅读、调试、git bisect 等操作

如果一个业务变更在宏观上可能涉及整理性工作（如重构、风格调整等），由于尺度宏观，其对项目工作量的影响不可忽略，应当搁置开发，先讨论方案

如果一个业务变更在微观技术细节上，不得不先做整理性工作才能加功能 / 改功能 / 删功能，应当先将整理工作组织为一个或多个单独提交，再行后续变更

如果一个业务变更在微观技术细节上，既可以先做 / 顺带做整理工作，也可以维持现状，建议先做整理工作；除非业务压力非常显著，此时应当将后续整理工作记录 issue 并关联。业务压力的判断采用客观标准，例如项目 delay 风险极高、HOTFIX、需求方咖位很高下班前就要，等等

特别地，研发过程中经常偶然发现一些改错别字、重新格式化等可做可不做的改进，建议顺手修掉，建议分拆单独 commit

Commit message

提交分类

必填，使用略有修改的 Angular 的分类定义

以下重复一遍描述并尽量给出示例。（排序为字母顺序）

分类 含义 备注
build 构建系统、外部依赖相关变更 如果此类变更有业务影响，优先适用 feat / fix
ci CI 配置、CI 脚本变更 -
chore 杂活 存在于老版本的 AngularJS 提交规范，最新的 Angular 提交规范中已经被细化为 build 与 ci 了。允许继续使用一段时间。建议使用更具体的分类
docs 仅修改文档 / 注释语义的变更 注释由于是给人看的，因此算作文档。本分类一定涉及语义的变更（措辞变化、内容新增 / 变更 / 删除等），单纯的错别字、排版修改算 style
feat 新功能；业务变更；语义变更 只要有任何外部可见的语义变更，都算作 feat / fix，不论影响大小，某种程度上也是托底分类。修复不预期的语义算作 fix。无语义变更的性能优化算作 perf
fix 修复不预期的语义 / 行为 -
perf 性能优化 仅限纯性能优化，不得包含任何外部可见的语义变更。如必须产生变更，建议考虑是否可以将纯性能优化部分独立出来。如确实无法分拆，整个提交算作 feat
refactor 任何不影响语义的代码变更。这是托底分类，如果有更具体的分类适用，则用具体分类 -
style 代码风格变更 仅限 whitespaces、换行、gofmt、拼写错误 / 错别字 / 标点符号修改等性质的变更。动到代码结构但没动到语义，算 refactor。有语义变更的注释变更，算 docs
test 测试代码变更 仅限单纯涉及单元 / 集成测试套件的变更，例如：加测试、补测试、改测试（fix build，健壮性优化等）、删测试（仅限删除不再适用的测试用例，禁止删除有作用的测试，即禁止削足适履）