代码提交规范

代码提交规范有三点必须严格遵守。

  • 控制好提交粒度,每次的提交都必须具有独立性和原子性。
    • 建议以一个功能点或 BUG 修复为单位;
    • 无直接关联的文件不能在同一次提交;
    • 除了初次提交,尽量不使用 git commit -a;
  • 认真对待提交备注信息,多花一分钟回想本次提交的代码所含的意义,清晰描述下来,具体可参见下文中的提交备注信息规范;
  • 最后,也是最重要的一点,不允许将会构建失败的代码推送到服务器端

注意:一次完整的构建过程包括预处理、编译、打包、单元测试和集成测试。

提交备注信息规范

为什么要关注提交备注信息

  • 加快 Reviewing Code 的过程;
  • 帮助我们写好 Release note;
  • 后续能够帮助开发人员快速想起来某次提交中增加了什么功能,改变了哪些代码;
  • 让其他的开发者在运行 git blame 的时候想跪谢。

一个好的提交备注信息,会帮助提高项目的整体质量。

基本要求

  • 第一行应该少于50个字,如:修复 BUG:#8976 登录后将用户转回登录前所在页面;
  • 第二行是一个空行;
  • 第三行是问题的详细描述。

如何更进一步(可选)

  1. 注释最好包含一个连接指向你们项目的 issue/story/card。一个完整的连接比一个 issue numbers 更好;
  2. 提交信息中包含一个简短的故事,能让别人更容易理解项目。

提交备注信息要回答如下问题

为什么这次修改是必要的?

要告诉 Reviewers,你的提交包含什么改变。让他们更容易审核代码和忽略无关的改变。

如何解决的问题?

这可不是说技术细节。看下面的这个例子:

为了改善搜索速度,引入了红黑树的实现。

当然,如果修改特别明显,可以忽略这点。

这些变化可能影响哪些地方?

这是最需要回答的问题。因为它会帮助发现在某个 branch 或 commit 中的做了过多的改动。

要保证一次提交尽量只做一件事情,比如修正一个 BUG,新增一个功能等。

其他细节小提示

  • 使用“修复 BUG”,“新增功能”等词语来为本次提交的内容定性;
  • 永远别忘了第 2 行是空行;
  • 用 Line break 来分割提交信息,让它在某些软件里面更容易读;
  • 请将每次提交限定于完成一次逻辑功能。并且可能的话,适当地分解为多次小更新,以便每次小型提交都更易于理解。

满足基本要求的例子

修复 BUG:#69 同步联系人失败,在消息界面中联系人名称已改变。

完整的例子

新增功能:#52 作为系统开发人员,需要编写代码,实现协议显示页面。

页面上显示协议文字,文字是固化在程序中,不通过网络读取,左上角有返回按钮,点击后返回起始协议页面。

results matching ""

    No results matching ""