Skip to main content
版本: 0.5.0

Git 提交指南

本文介绍了 Git 提交变更时需要注意的事项，如果拒绝接受本文的内容会导致提交的变更无法被接受。

1. 关于 issue​

在提交一个 issue 之前，请先查阅已经关闭的 issue ，也许在关闭的 issue 中已经存在合适的解决方案。

如果没有找到合适的方案，我们提供了4种模版在创建 issue 的时候使用。

  • Bug Report : 发现了一个 Bug，可以通过 Bug Report 模版创建 issue 与我们联系。
  • Enhancement : 开发者对工具进行了增强，可以通过 Enhancement 模版创建 issue 来介绍增加的内容。
  • Feature Request : 在使用的过程中想要为工具增加某些新的特性或者功能，可以通过 Feature Request 模版创建 issue 来描述新特性。
  • Ask a Question : 如果有任何的疑问，可以通过 Ask a Question 模版来创建一个 issue 与我们联系。

在选择合适的模版后，只需要填写模版上的要求填写的内容即可。如果在创建 issue 的时候发现没有模版，或者模版内容为空，可以通过微信群，钉钉群或者邮件向我们反馈这个问题。

2. 关于 Git 分支​

要向 kcl-lang 贡献代码，您必须拥有一个 GitHub 帐户，以便您可以将代码推送到您自己的分支并创建拉取请求。我们推荐参考 Angular 规范 为您自己的分支命名。 推荐的格式如下：

{type}-{a_short_description}

分支名称主要包括两个字段，并通过 “-” 分割。其中：

  • {type} : 当前分支内容的类型。
  • {a_short_description}: 一个简短的描述，介绍这个分支的主要内容。

e.g. 张三首先 Fork 仓库到自己账户下，然后创建对应名称 zhangsan:fix-output-fmt-bug 的分支（冒号之前是张三的账号），用于修复输出格式化 bug。

3. 关于 Git Commit​

我们参考 Commitizen 书写 Commit Message。

注: 如果直接使用 Commitizen 生成 Commit Message，需要注意因为 Commitizen 
是开发人员管理 commit 的工具，与项目本身无关联，因此由 Commitizen 生成的中间产物
(如: node_modules 文件目录)可能没有在项目 .gitignore 文件中。

您可以 git add {filename} 选择要提交的文件而忽视中间产物。
或者您可以向 .gitignore 文件中添加如下内容而自动忽视中间产物：
# commitizen 
package.json 
package-lock.json 
node_modules/*

如果手动编写 Commit Message，我们也建议采用 Commitizen 的 commit message 格式。

{type} ( {component_or_file} ) {a_short_description}
    {a_longer_description}
    BREAKING CHANGE: {breaking_change_description}.
    {linked issue}

其中主要包括6个字段：

  • {type} : 当前 commit 对应的分支的类型。

  • {component_or_file}: 当前 commit 改动的模块或者文件的名称。

  • {a_short_description}: 简短的描述介绍 commit 中的内容。

  • {a_longer_description}: 详细的描述用来介绍 commit 中的内容。

  • {breaking_change_description}: 如果 commit 中包含破环兼容性的改动，需要对兼容性改动产生的影响进行介绍。

  • {linked issue}: 与当前这个 commit 关联的 issue。

    其中 {breaking_change_description} 和 {linked issue} 如果 commit 中不包含破坏兼容性的改动和关联的 issue，可以省略。

    e.g. 张三在分支 zhangsan:fix-output-fmt-bug 中创建的 commit。


      fix(kcl-printer): fix an output format bug in kcl-printer
      
      There is an output format bug in kcl-printer because ...,
      So, The calling of method "XXX" is replaced by "HHHH"...,
      ...
      
      -- 如果没有破坏兼容性的改动和关联的 issue 可以省略下面内容。

      BREAKING CHANGE: This change maybe cause .......
      
      fix #123

4. 关于 pull request​

在提交一个 PR 之前，可能需要优先考虑以下几个问题:

  • 请先查阅已经关闭的 PR ，也许在已经关闭的 PR 中，可能存在已经完成的解决方案。
  • 我们建议在提交变更之前，提交一个对应的 issue 描述变更中将要解决的问题，并将变更对应的 PR 与 issue 关联。
  • 在向我们提交 PR 之后，请签署 Contributor License Agreement (CLA) ，如果拒绝签署，我们将无法接受 PR。
  • 请确保每次改动都创建了一个新的分支，并根据上文中提到的规范为分支命名。
  • 一次 PR 请不要超过两个 commit ，请将多余的 commit 通过 squash 压缩，并根据上文中提到的规范，编写 commit message 。
  • 我们提供了 PR 模版，只需要添加模版中要求的内容即可，如果在创建PR时发现没有模版或者模版内容为空，可以通过微信群，钉钉群或者邮件向我们反馈这个问题。

我们建议PR的标题与分支名、commit message 风格保持一致：

{type} ( {component_name_or_file_name} ) :{a_short_description}

e.g. 张三为分支fix/zhangsan/fix_output_fmt_bug创建的PR名称。

fix(kcl-printer): fix an output format bug in kcl-printer.

5. 目前 type 支持的类型​

参考Angular 规范，type 支持类型的类型如下:

- feat:     -- 添加了新的功能特性。
- fix:      -- 进行了 Bug 的修复。
- docs:     -- 进行了文档部分的修改。
- style:    -- 对代码格式的修改，并不影响代码的功能，如：删除多余空格，代码缩进等。
- refactor: -- 在不改变代码功能的基础上对代码进行了的重构。
- perf:     -- 对代码进行了性能优化。
- test:     -- 添加或者调整已有的测试用例。
- build:    -- 对构建系统或者外部依赖库进行了调整。
- ci:       -- 调整了 CI 的配置文件或者脚本。
- chore:    -- 对源代码和测试文件之外其他部分的调整。
- revert:   -- 对 commit 进行回滚。

6. Contributor License Agreement (CLA)​

在第一次向我们提交 PR 之后，在 PR 中的 CLA 检查将会失败并提示签署 CLA。您可以通过自己的账户之间在 PR 回复 "I have read the CLA Document and I hereby sign the CLA" 表示同意签署 CLA，然后手动重启失败的 CLA 检查 Action 即可。当 PR 被成功合并之后将会被锁定不能再修改。