エラーレポートからコード変更までをシームレスに接続する

ソースコード各行がどういった意図を持つのか、各変更がなぜ必要だったのかという経緯を把握することは、コードリーディングにおいて言うまでもなく重要なプロセスです。

しかしコードと合わせて貴重な文脈情報を記録するには多くの努力が必要だというのもまた事実です。いちいちコメントを残す手間も無視できませんし、そもそも変更の動機が文章化されているとも限らないからです。

本記事ではエラーレポートからコード変更履歴までをシームレスに接続する方法を紹介します。具体的にはGoogleFormsとGithubをGoogleAppScriptで連携させることで、Webフォームでエラーレポートを投稿すると自動的にGithub issueが起票されるよう設定します。

Githubが提供する数多くの機能の中でもissueやpull requestを相互に自動リンクできる機能は、コードトラッキングをする上で欠かせない機能です。

エラーレポートにとどまらず、新機能の提案や仕様変更にまつわる議論までプロダクトに関するすべての情報がGithub issueに集約されていればどれほど嬉しいことでしょう。コードを読みながら関係者を一人ひとりを訪ねて情報収集する必要はなくなります。

しかしながらGithubは万人のためのツールではありません。ユーザの向き不向きに応じて適切なUIを提供する必要があります。

偶然発見したエラーを報告するために滅多に使わないサービスのアカウントでログインし、慣れないマークダウンと格闘し、ようやく仕上げてもらったレポートには肝心なエラー再現方法が書かれていなかった。そんな結末はあまりにも残念です。

(1) レポート作成にログインが不要（もしくは日頃からログイン済みサービス）で、
(2) 簡潔なフォーマットが定まっていて、
(3) エラーが解決したあともレポートの価値が残る（コードベースと紐付く）、

このようなエラーレポートの方法があれば、報告者の負担も少なく、またエンジニア側も効率的に情報を探すことができます。

世の中にはたくさんの便利な（そして高価な）開発管理ツールがありますが、ここではとくにGoogleFormsとGithubを連携させることで実現させようと思います。 GoogleFormsなら(1)と(2)はある程度の改善が見込めそうです。(3)についてもGithubへ情報をエクスポートできれば解決できます。

前置きが長くなりましたが、仕組みの構築自体はGoogle/Githubが提供しているサービスを使うので多くを説明する必要はないと思います。彼らの提供するWebコンソールは日々使いやすいようにアップデートされているため、構築方法をスクリーンショットつきで仔細に説明してもすぐに古くなってしまいます。

その代わり、GoogleForms <-> Github issueの連携のキモとなるGoogleAppScriptのソースコードを載せておきます。

gist.github.com

headers 変数にはGoogleFormsで作成した質問項目のタイトルをいれます。

スクリプト中段のtokenにはGithubのPrivateAccessTokenを設定してください。権限はrepoが必要です。

REPO_OWNER および REPO_NAME はissueを作りたいGithubリポジトリの値で置き換えてください。

両サービスの連携が正しく設定できれば、本記事添付のスクリーンショットのようにGoogle Formsで投稿した内容をもとに自動でGithub issueが起票されます。

ちなみに読みやすいブログ記事を書くためには「ですます調」を心がけると良いらしいです。本記事でさっそく試してみました。