GitHubのissueの書き方を解説！何を記述するべき？

GitHubには数多くのオープンソースソフトウェア(OSS)が公開されています。これらのソフトウェアを使っていると、バグを発見したり要望が生まれたりしてきます。この記事ではissue機能を用いてそれらを開発者に伝える方法を説明していきます。

「自分で報告するのは気が引ける」という方も、この記事で紹介する項目が参考になると思うので是非確認してみてください。

issueはそのソフトウェアプロジェクトにおいて非常に貴重な財産になります。実際に使用しているユーザからのフィードバックを受けて、バグ修正等が行われていくことでソフトウェアの質を向上させていくことができるので、積極的に書いていきましょう。そうすることで、開発者とユーザ(自分以外も含む)の両者にとって価値のあるものにすることができます。

ここでは、どのようなことを気をつけて書けば良いのかを考えてみます。

僕は、必要な情報が過不足なく簡潔に伝わるものにすることが大事だと思っています。

開発者はユーザからのフィードバックを受けてソフトウェアの改善・修正を行います。ここで、開発者は「ユーザが抱えている問題は何なのか」や「ユーザが望んでいる機能は何なのか」、「何故それが必要なのか」などを知りたがっています。ユーザとしても、抱えている問題の解決が適切にされることを期待しています。そのため、これらが明確に伝わるようにすることを意識する必要があります。

僕は書き始める前に確認するべきことは大きく三つあると考えています。

1つ目は、本当にissueにするべき内容かどうかを考えることです。出鼻を挫くようですが、これは大事なことです。無駄な内容をたくさん投げてしまうと、開発者の管理コストを上げることになってしまうので注意しましょう。

具体的には、開発者へのリクエストやバグ報告にのみ用いるようにしましょう。そのソフトウェアの開発者や管理者に伝えることに意味がある内容かを考えると良いと思います。

一番多いのは、単にそのソフトウェアの質問を書いてしまうことです。質問箱ではないので、単純な質問はStack Overflowやteratailなどに登録をして投稿しましょう。規模の大きいソフトウェアでは、コミュニティの運営するメーリングリストなどがあったりするのでそれらを利用するのも良いです。

このような質問は公開されているドキュメントをしっかり読めば解決することも多いので、まずはそれらを読んでみましょう。逆に、「ドキュメント(README)に誤りがある」などはこの場で修正リクエストをしても良いかもしれません。

2つ目は、issueを書くべきリポジトリが適切かを確認することです。

そのプロジェクトの対応範疇でない内容が投稿されていることがたまにありますが、これは良くありません。正しいリポジトリに書き込むようにしましょう。複数のツールやライブラリを同時に用いている場合などにこの誤りは起こりがちです。

3つ目は、同じissueが既にあがっていないか確認をすることです。重複すると無駄になってしまいますし、開発者の手間になるだけなので気をつけましょう。既にある場合(未解決の場合)、追加情報を与えられるのであればコメントとして追加情報を記述しましょう。後述する「書くべき内容」を参考にしてみてください。

また、既存の投稿は解決済みのものも含めて確認しましょう。この場合、解決方法が記載されているか、対応済みのバージョンがリリースされていることが多いので参考にしてください。

まず、対象となるリポジトリのGitHubページにアクセスをします。そして、タブ部分からissueのタブをクリックします。

タブをクリックしたら以下のような画面に遷移するので、右下の「New issue」をクリックします。

書き込むためのフォームが表示されるので、タイトルと本文を書き込んで送信をしましょう。

それでは、実際にどのような内容を記載すれば良いのかについて話します。基本的には、書くべき内容は以下の4つです。

リポジトリ毎に記載内容が指定されていることもあるので、その場合はリポジトリ毎の取り決めに従いましょう。逆にリポジトリの管理者の方は、このような内容でテンプレートを作っておくと良いです。

そのツール自体のバージョンや、依存していそうなソフトウェアとそれらのバージョン(OS、依存パッケージ、ホスト言語など)を記載しましょう。開発者がなるべく同じ環境を再現できるように具体的に書くのが望ましいです。

具体的に何をやろうとしたのかを記載しましょう。また、入力として与えた値や問題が起こる直前に行ったことなどの解決に繋がりそうな情報も一緒に記載するようにしましょう。実際に仕様したコードや、その状況が発生するサンプルコード、スクリーンショットや動画などを貼るとより親切です。

自分がどのような結果になることを想定していたのかを記述しましょう。自明な場合は省略しても構いません。場合によっては、自分が期待していた結果がそもそも仕様上正しくないということもあり得ます。

「正しくない計算結果が出た」、「予期しないエラーが発生した」、といった結果を記載しましょう。この項も、実際の値などを用いて極力詳細な結果を提供するようにしてください。長いエラーメッセージを全てそのまま貼り付けるのは可読性を損なうので、そのような場合は必要な部分のみを切り取って記載しましょう。

実際に書く際に、本記事の内容を参考にしていただければ幸いです。ユーザと開発者の両者にとって有益なものになるので、積極的に行なっていきましょう。