【GitHub】チームの情報粒度を揃えるためのissue formsテンプレートの作り方

はじめに

こんにちは。フロントエンド開発課に所属している新卒1年目のm_you_sanと申します。
今回はissue formsを使ってGitHub Issuesのテンプレートを作成する方法について、紹介したいと思います。

はじめに
issue formsとは？導入するメリットは？
作り方
まとめ

issue formsとは？導入するメリットは？

issue formsは、GitHub上で提供されるGitHub Issuesに入力フォームを追加する機能です。

GitHub Issuesでは、デフォルトで大きめのテキストエリアが１つ提供されていますが、そのまま運用すると以下のような問題が起こります。

具体的に何を書いて良いのかわからない
人によって記載粒度にばらつきがある
欲しい情報が記載されていない場合がある

上記の問題はMarkDown形式のテンプレートでも、ある程度改善することはできますが、記入者がテンプレートを無視して自由に記載できてしまうなどの欠点があります。

一方でissue formsでテンプレートを作ることで、小項目に分けることができるので、記入者がどこに何を書けば良いのかが明確になります。
また、MarkDown形式のテンプレートと異なり、記入者がテンプレートを無視することができないため、記入者による書き方のばらつきが起こりにくくなります。
加えて、条件付きではありますが、issue formsでは必須項目の指定ができるので、欲しい情報を記入者に入力させることが可能です。

作り方

今回は例として、バグ報告用と改善・リファクタ用のテンプレートを作成します。
まずプロジェクト直下に.github/ISSUE_TEMPLATE/を作成し、その下にyamlファイルを置きます。

//ディレクトリ構成
.
├── .github
│   └── ISSUE_TEMPLATE
│       ├── bug_report.yml
│       ├── enhancement_request.yml
│       ├── config.yml
:

次にbug_report.ymlを編集します。

# bug_report.yml
name: バグ報告
description: 不具合報告はこちら
title: 'Bug: '
body:
  - type: textarea
    id: overview
    attributes:
      label: 概要
      description: |
        不具合の概要を記載してください。
        見た目に関係する場合は、スクリーンショット等を貼り付けてください。
    validations:
      required: true
  - type: input
    id: environment
    attributes:
      label: 再現環境
      description: |
        再現環境を記載してください。
        例：
        Chrome + Windows
        Edge + Windows
        Chrome + macOS
        Safari + macOS
    validations:
      required: true
  - type: textarea
    id: process
    attributes:
      label: 再現手順
      description: 不具合を再現させる手順を記載してください。
      value: |
        1. 
        2. 
        3. 
        ...
    validations:
      required: true
  - type: textarea
    id: supplement
    attributes:
      label: 補足

キーの詳細は以下の通りです。

キー	説明	必須
name	テンプレートの名前。一意である必要があります。	〇
description	テンプレートの説明。名前の下に表示されます。	〇
title	タイトルに事前に入力されているテキスト。	×
body	フォーム全体の内容。	〇
type	フォームの要素。 checkboxes、dropdown、input、markdown、textareaの中から指定できます。	〇
id	フォーム要素の識別子。フォーム定義内では一意である必要があります。	×
attributes	フォーム要素のプロパティを定義するキーと値のペア。	〇
label	フォームのラベル。	〇
description	フォームの説明。ラベルの下に表示されます。	×
value	事前にフォームに入力されているテキスト。	×
validations	フォームのバリデーションを定義するキーと値のペア。	×
required	trueにすると入力必須になります。 publicリポジトリの場合のみ有効になります。	×

同じようにenhancement_request.ymlも編集します。

# enhancement_request.yml
name: 改善・リファクタ
description: 改善・リファクタはこちら
body:
  - type: textarea
    id: background
    attributes:
      label: 背景
      description: どのような課題を抱えてissueを立てたのか、経緯や前提を記載してください。
    validations:
      required: true
  - type: textarea
    id: merit
    attributes:
      label: メリット
      description: 改善することでどのようなメリットがあるのかを記載してください。
    validations:
      required: true
  - type: textarea
    id: do
    attributes:
      label: やること
      description: このissueで取り組むことを記載してください。
    validations:
      required: true
  - type: textarea
    id: supplement
    attributes:
      label: 補足

最後にconfig.ymlを編集します。
このconfig.ymlは、新しくissueを作成する際に表示されるテンプレート選択画面をカスタマイズするためのファイルです。
今回はblank_issues_enabledをfalseにすることで、issue formsで作成したテンプレートのみを選択できるようにしています。

# config.yml
blank_issues_enabled: false

push後、画面を確認して以下のようになっていれば完成です。

まとめ

今回は、issue formsでGitHub issuesのテンプレートを作成する方法について紹介させていただきました。
私が所属しているチームでは、実際にissue formsを運用しているのですが、デフォルトのテンプレートを使っていたときに比べて、issueの管理がしやすくなったので、気になった方は是非試してみてください。

参考資料

docs.github.com