Issue の立て方、本当にそれで良いの？

GitHub などで Issue を立てることは多いと思いますが、あまりに適当に立てる人が多すぎるよなぁと。

レビューについてはマナーやルールを意識する人がちらほら見かけられるんですが。

自分が Issue を立てる際に心がけていることを書いていこうと思います。

今日その現場に入ってきた人にも伝わるように書く

一番良くない Issue の立て方に、assign した人にだけ伝われば良いや、みたいなノリで書くことだと思っています。

Issue って open したら始まりで、close されたら終わり、ではありません。

そのリポジトリのログとして残り続ける以上、あとから誰かがその Issue を読んだときにも、きちんと伝わるように書くことがとても大切です。

例えばフロントエンド用のリポジトリであれば、どの画面のどの箇所で、どのような挙動が行われており、どういった挙動が望ましいのか。

また、なぜその挙動が起きていると思われるか、どうすれば対処できると思っているのかなど、なるべく細かく、かつシンプルにわかりやすく書いておくことがとても大切です。

どんなケースであっても、Issue タイトルだけ書いて詳細を書き下さないなんて論外です。

わかりやすい言葉を使う

その現場でのみ通用する言葉や略称、一般的でない言い回しや横文字は避けるべきです。

使用するのであれば、README にその旨を書いておくとか、何らかのフォローが必要かと思われます。

なぜか横文字を多用するエンジニアがって少なくないですけど、あれなんなんですかね？

誰にでも伝わる表現を使用することが大切だと思います。

言葉を統一する

これもすごく困るのですが、なーぜか言葉遣いをいちいち変えて書く人がいます。

例えば多いのが「取り消し」という言葉。

figma 上に「取消」というラベルが書かれていたとして、Issue 上では「取り消しラベル」と書かれると、コードを検索する際に非常に困ります。

『「取消」と書かれているラベル』という表現であったり、「取消ラベル」といった表現で書いてほしいですね。

こういった気遣いを行わないと、無駄な時間がかかって誰も得しません。

slack や figma などへのリンクを貼らない

賛否両論あると思いますが、自分は他サイトへのリンクはなるべく避けるべきだと思っています。

パッケージの公式サイトや Stack Overflow などであればまだ許容できますが、そういったケースであってもリンクを貼るだけでなく、引用まで行うべきです。

もし仮に他サイトへのリンクのみを貼り付けていたとして、そのサイトがなくなってしまったり、URL が変更された場合に、どうしようもなくなってしまいます。

また slack や figma など、プロジェクトの内部でのみ使用されているツールへのリンクは避けるべきです。

もし仮に、そのリポジトリが OSS に方向転換しようとした場合、そういったリンクは大きく足を引っ張ります。

また、その URL が保持される保証もない以上、引用に留めるのがベターではないかと思っています。

スクリーンキャプチャを貼らない

文字で書くのが面倒だからといって、slack などのやり取りをそのまま貼り付けるのは愚の骨頂です。

理由は単純で、検索で引っかからないからです。

ログとしての意味をなさないため、やはり引用や、自分の言葉で書くことが大切だと思います。

Issue の close 条件を書く

これもよく見かけますが、Issue を立てたのは良いけど、閉じる条件がわからず放置され、結果的に Issue が乱立してしまうケースです。

Issue の粒度は、どちらかといえば細かいほうが望ましいと思いますが、Feature request などのケースでは漠然とした Issue を立てざるを得ないこともあると思います。

そういった Issue を立てるときは、必ずその Issue の close 条件を付与してやると、その Issue の目的が多少明確になります。

close 条件すらも漠然としている場合は、そもそもその Issue を立てる必要があるのか？といったところから考え直したほうが良いかもしれません。

Assign と Milestone を必ず付与する

とはいえ、Issue は乱立してしまうものです。

なぜ close されない Issue が生まれてきてしまうのか。

個人的には、close 条件が明記されていないことに加え、以下も大きな理由だと考えています。

• Assign が割り振られておらず、みんな誰かが close してくれるだろうと思ってしまっている
• Milestone が割り振られておらず、期限がないためいつまでも取り組まない

したがって逆に考えれば、Assign を Milestone を必ず割り振るフローを取れば、理屈の上では絶対に Issue は残り続けません。

特に Milestone に限って言えば、よく Milestone を割り振ることに苦戦しているプロジェクトを見かけますが、それはその Issue 自体が不必要なのでは？と思うことも少なくないです。

大切なことは、例外を許容しないことだと思います。

Issue を立てるくらいで例外を許容していては、そのプロジェクトは全然ダメです。

きちんとしたフローのもと、ルールに沿って開発を行っていけば、絶対にプロジェクトの破綻は起きません。

あなたの現場のリポジトリ、いつまでも open されっぱなしの意味不明な Issue が残っていませんか？