はじめに
ある日、プロジェクトのschema.resolver.goファイルが突如としてGitHub上でgenerated fileと判定され、プルリクエストの差分に表示されなくなる問題に直面しました。
「Some generated files are not rendered by default」となり差分が表示されない様子
schema.resolver.goファイルは、GraphQLサーバーの実装ファイルでgqlgenによってメソッドのシグネチャのみが自動生成されますが、その実装部分は我々が記述しなければなりません。そのため、コードレビューは不可欠ですが、GitHubで差分が表示されなくなったことでレビューが困難になり、その解消方法に頭を悩ませることになりました。
この記事では、本事象が発生した原因と解決方法、プルリクエスト上で差分を表示させない方法について説明していきます。
明示的に差分を非表示にする方法
GitHubは、あるファイルがgenerated fileであると判断した場合、その差分は表示されません。これにより、自動生成されたコードがレビューのノイズになることを防ぎます。
一般的に、GitHub上で差分を非表示にするには、.gitattributesファイルでlinguist-generated属性を設定する必要があります。
file/path linguist-generated=true
しかし、今回問題となったschema.resolver.goは、linguist-generated属性を設定していませんでした。
暗黙的に差分が非表示になるロジック
GitHubでは前述したような手動でgenerated fileと明示する方法の他に、言語毎にgenerated fileと自動判定するロジックが存在しています。
このロジックを調査したところ、Go言語では// Code generatedというコメントがファイル冒頭に含まれると自動的にgenerated fileと見なされることが分かりました。
問題の原因
schema.resolver.goの内容を確認したところ、まさに// Code generatedというコメントがファイル冒頭に追加されていることが判明しました。
このコメントはgqlgenのバージョンv0.17.21以上で新たに挿入されるようになったもので、gqlgenをアップデートした際に追加され、このバージョン以降GitHubがgenerated fileと判断する要因となったのです。
解決方法
この問題を解消するには、.gitattributesで明示するか、gqlgenの設定ファイルで// Code generated部分の生成を省略するか、2パターンの解消方法があります。
1. .gitattributesで明示する
前述したように、.gitattributesファイルでlinguist-generated属性を用いることで、GitHub上で差分の表示条件を明示的に設定できます。
ここでは差分として表示したい（＝生成ファイルと判定してほしくない）ため、linguist-generated=falseを設定します。
path/to/schema.resolver.go linguist-generated=false
2. gqlgenの設定ファイルで// Code generated部分の生成を省略する
見出しの通り、gqlgenではコードコメントの生成を省略する設定が可能です。
omit_gqlgen_file_notice: true # ファイル冒頭のコメント（`// Code generated`を含む）を省略
これによりschema.resolver.goを再生成すると、冒頭のコメントが削除されていることが確認できます。
package hoge
- // This file will be automatically regenerated based on the schema, any resolver implementations
- // will be copied through when generating and any unknown code will be moved to the end.
- // Code generated by github.com/99designs/gqlgen version v0.17.30
まとめ
この記事では、schema.resolver.goがGitHub上で「generated file」として扱われ、差分が表示されなくなった問題の原因と解決策について説明しました。
原因はgqlgenのアップデートで追加された// Code generatedコメントがGitHubの自動判定ロジックに引っかかったことでした。私はこの自動判定ロジックの存在を知らなかったため、解決までに手間取りました。
GitHubは言語ごとに異なる基準でgenerated fileを判定しています。特にレビューが必要な自動生成ファイルを扱う際には、この判定ロジックを認識しておくと役立つでしょう。
再掲
「物流の次を発明する」をミッションに物流のシェアリングプラットフォームを運営する、ハコベル株式会社 開発チームのテックブログです！ 【エンジニア積極採用中】t.hacobell.com/blog/career
Discussion