Computer Science Radar

Commit Message

不同的项目有不同的约定式提交，最早出现于 Angular。本文中摘录三种约定式提交规范。

  • Angular
  • jQuery
  • gitmoji
  • Taichi
  • ...

使用约定的提交信息有几个好处：

  • 助于组织和记录开发信息
  • 自动生成 CHANGELOG，git log <last tag> HEAD --pretty=format:%s
  • 在提交历史中提供更友好可读的信息

Angular§

AngularJS Git Commit Message Conventions

格式§

header-body-footer

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
  • type，此次变更的类型
  • scope (可选)，受影响的npm包名
  • subject，对变更的简要描述
    • 使用命令式的动词原形，"change" not "changed" nor "changes"
    • 首字母不大写
    • 结尾不使用句点
  • body (可选)，对变更的详细描述
    • 与 subject 相同，使用命令式的动词原形
    • 包括变更的动机，并与之前的内容对比
  • footer (可选)，Breaking Changes？

type§

  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests

scope§

  • animations
  • common
  • compiler
  • compiler-cli
  • core
  • elements
  • forms
  • http
  • language-service
  • platform-browser
  • platform-browser-dynamic
  • platform-server
  • platform-webworker
  • platform-webworker-dynamic
  • router
  • service-worker
  • upgrade

Conventional Commits§

结构§

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

type 后添加 ! 表示较大变更（BREAKING CHANGE）。

规范§

摘录部分关于首行内容的规范，全部规范请参考原文。

参考 RFC 2119，规范中使用以下的关键字用于描述，“必须（MUST）”、“禁止（MUST NOT）”、“必要（REQUIRED）”、“应当（SHALL）”、“不应当（SHALL NOT）”、“应该（SHOULD）”、“不应该（SHOULD NOT）”、“推荐（RECOMMENDED）”、“可以（MAY）” 和 “可选（OPTIONAL）” 。

  1. 每个提交都必须使用类型字段，其后接可选的范围字段，可选的 !，以及必要的冒号（英文半角）和空格。
  2. 当一个提交为应用或类库实现了新功能时，必须使用 feat 类型。
  3. 当一个提交为应用修复了 bug 时，必须使用 fix 类型。
  4. 范围字段可以跟随在类型字段后面。范围必须是一个描述某部分代码的名词，并用圆括号包围。
  5. 描述字段必须直接跟在 <类型>(范围) 前缀的冒号和空格之后。 描述指的是对代码变更的简短总结。

Taichi§

高性能图形学基础设施项目 Taichi，作为开源项目，对 PR 命名做了约定。

因为 Taichi 采用 squash rebase 的工作流，所以 PR 的命名约定也相当于提交信息约定。

格式§

[tag1] [tag2]...[tagN] Your PR title must be short but carry necessary info

^----^ ^----^...^----^ ^--------------------------------------------------^

|      |        |      |

|      |        |      +---> Capitalize the initial of your title.

|      |        +---> Adjacent tags are separated with precisely one space.

|      +--->  Frequently used tags: [cuda], [lang], [ci], [ir], [refactor].

+--->  Prepend at least one tag to your PR title.
  • 使用方括号包住类型 tag
  • 一次提交时至少使用一个 tag，多个 tag 使用一个空格分隔
  • PR 的 title 首字母大写
  • 如果 PR 处理的是终端用户可见的功能，tag 需要首字母大写或全大写，[Metal], [Vulkan], [IR], [Lang], or [CUDA]
  • 如果 PR 处理的是底层或内部实现，tag 使用全小写，[metal], [vulkan], [ir], [lang], or [cuda]

tag§

常用 tag 的说明：

  • [cuda]: Backend-specific changes.
  • [lang]: Frontend language features, including syntax sugars.
  • [ir]: Intermediate representation-specific changes.
  • [refactor]: Code refactoring changes.
  • [ci]: CI/CD workflow-specific changes.
  • [Doc]: Documentation updates.

完整列表在这里 taichi/prtags.json at master · taichi-dev/taichi (github.com)

在实际的 Git 协作中有体会，本地的每条提交在 PR 时可以通过 git rebase -i 重写，不必每条都加上 tag。采用首字母大写的提交信息就是一种方式，只需要在提交 PR 时进行合适的命名。

Reference§

  1. Git Commit Message Conventions - Google 文档
  2. Git 提交记录和分支模型 (cattail.me)