项目缺少代码格式化工具约定

[longyue0521]

问题描述:

当我为项目添加代码并保存时,我发现有很多“修改”都是代码格式化导致的,这在代码审查时会是干扰.

改进意见:

1. 指导开发者为其IDE(Goland/VSCode)配置统一的代码格式化工具
2. 提交前强制格式化代码,在.github/pre-push里加入运行代码格式化工具
3. 可选工具gofmt或gofumpt,也可两者一起用

[flycash]

好建议！目前我们有一个 make setup 的命令，不过只是简单的运行 golint。这个命令的设计初衷，就是用来初始化开发环境的。

目前来看，我觉得我们先加一个 gofmt 进去。同时提供一个 make fmt 命令，这样后续用户永远只需要自己手动运行一下 make fmt，或者在 pre-push 的时候强制触发一下。

gofmt 或者 goimports，gofumpt 都可以。

但是我只有一个要求，如果工具不能调整的格式，就不能要求贡献者手动调整。手动调整格式一个性价比很低的事情。

关于 gofmt 还是 gofumpt，以及 goimports，我并没有特别强烈的偏好。如果你愿意，你可以在这里继续讨论这三者的差异，以及你最终觉得应该选择哪个。

[longyue0521]

我测试了一下

1. 安装goimportsgo install golang.org/x/tools/cmd/goimports@latest和gofumptgo install mvdan.cc/gofumpt@latest
2. 在eorm根目录中先执行goimports -w . && git add .,再执行gofmt -w .发现无变化(证明Go官方的goimpots确实可以替代gofmt),再执行gofumpt -w .发现少量无关紧要的变化——函数/方法末尾是否空一行等
3. 分析

• gofmt无法处理improts部分
• goimports由Go官方维护且兼容gofmt并能处理源码中imports部分,并且在文档中表明In addition to fixing imports, goimports also formats your code in the same style as gofmt so it can be used as a replacement for your editor's gofmt-on-save hook.
• gofumpt由社区维护,还在发展中未来情况不可预知,现阶段与goimports差异很小,优势在于可以自定义格式化

结论,使用最新版的goimports

要做哪些事

1. 在script/setup.sh中添加安装goimports, go install golang.org/x/tools/cmd/goimports@latest的shell
2. 在Makefile中添加一个make fmt命令供用户使用
3. 在.github中添加一个pre-commit hook, 提交前运行goimports, 如果在pre-push中,添加好像会出现test和linter都过了,文件恰巧格式化了但格式化后的文件并不在本次push中的情况.当然也可以用goimports -l -w . 有输出就报错不允许push但觉得不友好.

[flycash]

可以的，就使用 goimports，然后放在 pre-commit。这种执行很快的命令放在 commit 没什么问题。但是我们还需要一个 github action 来检测，一个独立的 github action，也就是如果用户没有格式化代码，那么这个action就会失败，然后我们打上一个标签，”请格式化代码“。这样我觉得按照很普通的开发者的水平，估计也能看懂了

[longyue0521]

1. 我在本地已经将make fmt、pre-commit和script/setup.sh测试好了
2. 这个action就会失败，然后我们打上一个标签，”请格式化代码“往哪里打标签?Pull Request?
3. 找了半天只有下面这两个github action,但好像不符合要求
   • https://github.com/marketplace/actions/check-golang-imports-order
   • https://github.com/marketplace/actions/goimports-check-action

替代方法是在.github/workflows/go.yml中添加

     - name: 检查项目依赖及代码格式
        run: |
          go install golang.org/x/tools/cmd/goimports@latest &&
          go mod tidy &&
          goimports -w .
          # 利用git status列出变更的文件来中断CI并提示错误
          if [ -n "$(git status --porcelain)" ]; then
             echo >&2 "错误: 请在本地运行命令'go mod tidy'及'make fmt'后再提交."
             exit 1
          fi

4. 是否需要开个issue来记录这次变更,还是直接发起Pull Request?
5. 提交时,只包括make fmt、pre-commit、script/setup.sh和.github/workflows/go.yml这些建立机制的更改,还是将格式化后的29个文件一并提交?

[flycash]

1. 赞
2. 往合并请求上打标签，这个稍微有点难，因为需要权限控制，暂时打标签的功能不必实现。我觉得贡献者在看到格式化输出的错误信息，也能理解出了什么问题
3. 新开一个，workflows/go-fmt.yml
4. 我连接到这个 discussion 就可以了
5. 一并提交

[longyue0521]

commit-message 是否也需要统一标准呢?

1. 用户在提交commit时,弹出统一commit模版,按照统一要求编写commit message.
   • git commit -s -m "xxxx"要添加-s签名
2. 添加hook检查用户填写的commit是否符合要求,不符合要求要报错并中断提交.

• https://medium.com/dev-chill/%E4%BD%BF%E7%94%A8-git-commit-template-%E7%AE%A1%E7%90%86-git-log-cb70f95fda2f
• https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration
• https://gist.github.com/lisawolderiksen/a7b99d94c92c6671181611be1641c733
• https://stackoverflow.com/questions/21998728/how-to-specify-a-git-commit-message-template-for-a-repository-in-a-file-at-a-rel

[flycash]

很多人不具备这样的能力，就是写好 commit message 的能力。所以实际上我现在都是在合并请求的时候使用 rebase and merge，然后重写的一个 commit message。
commit message 本身重点在于内容。格式反而不是很重要，所以暂时我觉得不必强求。

[longyue0521]

好的