Github issue との付き合い方 作成編
仕事で Github を使っていたり、 OSS への contribute しようと思ったときに issue を作成することがあると思うが、最近の Github の機能追加もあって、ベストプラクティスが共有されてない感があるので、おれはこうしているということや、アドバイス募集の意味も含めて書こうと思う。
まずは issue を作成する際、頭にいれておいたほうがいいことについて。
ドキュメント
Github の公式ドキュメントがあるのでまずざっと目を通しておくとよい。
issue とは何か ?
読み方は「イシュー」。直訳すると「議論すべき重要な話題・論点・争点」 / 「関心事」あたりになる。
Github repository ごとに issue を作成・管理できる。 issue ではその repository が見られれば誰でも発言でき、議論・報告・連絡・提案などもろもろが可能。 issue ごとにタイトルが必須なので、通常タイトル絡みのことが話される。
repository 管理者の方針によるが、機能実装やコミュニティの運営方針の議論などに使う場合もあるし、仕事で使う際は単純にタスク単位に issue を切って管理していくためのツールとして使われることも多い。
議論する際の使われ方のイメージとしては質問サイトなどが近い。質問サイトでは特定の質問に対してみんなが答えていくが、質問の投稿 = バグ報告・新機能提案などにあたる。
タスク管理ツールとしての使い方だと Todo ツールなどに近い。 issue 単位で Todo = やることを書いていく。いつまでにやるか ? などは issue ではなく milestone という仕組みで管理するので、個人用ではなくチーム用だが。
issue の作成方法
Issues タブから New Issue を押すと入力ページになる。
必須入力欄は Title のみだが次のことに気をつけよう。
- わかりやすく簡潔な Title になっているか ?
- comment は誰が見てもわかるようになっているか ?
わかりやすく簡潔な Title になっているか ?
すべての事柄を説明・主張を表現でき、かつ誰が見ても誤解がないような Title がベスト。十分にわかりやすいという確信が持てたら comment は書かなくてよい。が、たいていそんなに物事は単純ではない。
issue は repository の関係者にとって非常に有益な情報になる反面、管理者にとっては手間が増える。特に人気の OSS などでは 1 日に何十件も issue が作成されることもあるので中身を見て判断するのは現実的でない。 Title だけでバグのインパクト、提案の有用性がわかれば管理者もうれしい。というかわからないものは閉じられても文句は言えない。それではせっかく issue を作成したあなたの時間も無駄になる。
わかりやすい Title を書くのであればまず comment から考えるとよい。バグはどういうものか / 提案のメリデメは何か、などを考えよう。
comment は誰が見てもわかるようになっているか ?
どういう issue を作成するのかで各論になる。
バグ報告
テンプレートが整備されている場合もあるが、次を明確にするとよい。
- as is: いまどういう状態になっているか ?
- to be: どういう状態が望ましいか ?
- environment: どういう環境で as is の状態になったのか ?
- to reproduce: environment 上でどういう操作をすると as is の状態になるのか ?
- frequency: to reproduce を繰り返したときに何度 as is の状態になるのか ?
この場合、 as is の内容を簡潔に表現すると Title としてふさわしいことが多い。
また、スクリーンショットがあると一目瞭然なのでできるかぎり添えて issue を作成しよう。
as is: いまどういう状態になっているか ?
---------------------------------------
ログインしたユーザー名が右上に表示されない
to be: どういう状態が望ましいか ?
---------------------------------
ログインしたユーザー名が右上に表示される
environment: どういう環境で as is の状態になったのか ?
------------------------------------------------------
Firefox 52.0
macOS Sierra 10.12.4
to reproduce: environment 上でどういう操作をすると as is の状態になるのか ?
---------------------------------------------------------------------------
未ログイン状態からログインする
frequency: to reproduce を繰り返したときに何度 as is の状態になるのか ?
-----------------------------------------------------------------------
5/5
提案
こちらはその提案によってどんなメリデメがあるのかを明確にすればよい。
- 問題
- 提案内容
- 既存からのメリット・デメリット
- 既存ユーザーへのインパクトがある場合、移行計画
たいていの場合、デメリットがメリットを上回れば前向きな議論になるが、ソフトウェアが動かなくなる可能性があったり、ユーザーに対処してもらう必要がある場合など、既存ユーザーへのインパクトが大きすぎる場合は移行計画がないと「現実的じゃないよね」で終わる。
Title には提案内容を書くのがよいか。
問題
----
API `registerUser` の責務が大きすぎる
登録後の確認メールを不必要とするユーザーに対応できない
提案内容
--------
`registerUser` 内のメール送信部分を `sendMail` として独立させる
既存からのメリット・デメリット
------------------------------
登録後の確認メールを不必要とするユーザーに対応できる
既存ユーザーへのインパクトがある場合、移行計画
----------------------------------------------
API に version を追加し、次バージョンからこの提案内容とする
http://example.com/api/registerUser
↓
http://example.com/api/v2/registerUser
http://example.com/api/v2/sendMail
タスク
タスクとは「前工程の成果物を入力として後工程に続く成果物を作成する」活動のこと。
何言ってんだおめえという場合は逆算すればよい。
- 成果物: タスクが終わると成果物として何ができるのか ?
- 入力: 成果物を作成するために必要な入力は何か ?
- 作業: 成果物を作成するためにどういう作業が必要か ?
作業内容を Title に書くとよい。
成果物: タスクが終わると成果物として何ができるのか ?
----------------------------------------------------
ユーザーの趣味をひとつ入力・保存・変更・表示できる機能とそのテスト
入力: 成果物を作成するために必要な入力は何か ?
----------------------------------------------
- ユースケースは社内 wiki 参照
- 命名規則は既存ソースコードのインターフェイスを参考に
- テストケースと粒度も既存ソースコード
- この前先輩にハナシを聞きながら書いたメモ
- ESLint についてはググる
作業: 成果物を作成するためにどういう作業が必要か ?
--------------------------------------------------
- インターフェイスを決める
- テストを書く
- 保存ロジック
- 値変更ロジック
- 値取得ロジック
- 実処理を書く
- ESLint をとおす
markdown について
comment は markdown で書くことになるが、最低限次を覚えておけばよい。
- URL
- コピペすればそのままリンクになる
- 画像
- ドラッグ & ドロップでそのまま表示される
- 10 MiB の制限がある
あとは次を見ながら徐々に覚えていけばよい。
label について
repository ごとに label のつけかたを決めていたり決めていなかったりするが、↓のようにガイドラインが用意されていたり、テンプレートに明確にこうしろ、と書かれていない限り作成者はあまり気にしなくてよい。
ガイドラインは熟読するようにしよう。
その他
- ひとつの issue にひとつの事柄を徹底すること
- バグ報告や議論の際は建設的になるよう心がけること
- 議論の仕方など本などで学ぶとよいかもしれない
- とりあえずやってみること
- 不安なら自分で repository を作ってそこで練習するでもいい
- もしくは↓などで練習