GitHubの新しいissue forms機能（ベータ）を試したメモ

すごい。知らなかった。issue作成時にフォームを表示できる／New Issue · pypa/pip https://t.co/iIO2OVkBZt pic.twitter.com/CfH6ifDlPh
— Shingo Yamazaki (@zaki___yama) 2021年6月16日

こちらのツイートをしたときはまだ一部のリポジトリしか有効になってなかったんだけど、先日ついにすべてのパブリックリポジトリで利用可能になった。（まだベータという位置づけ）

というわけで自分のリポジトリで試したメモ。

ドキュメントはここにある。

https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms

issue forms機能とは

GitHub には元々 Issue のテンプレート機能があったが、テンプレートファイルを Markdown でなく YAML で用意すると issue 作成時にフォームで表示してくれるというもの。

実際の画面キャプチャを載せる。
https://github.com/zaki-yama-labs/github-issue-forms-playground で New issue すると見れる。

f:id:dackdive:20210629235241p:plain:w480

自由記述式のテキスト項目だけでなく、ドロップダウンやチェックボックスも作れる。

設定方法

Markdown のときと同じく、リポジトリに .github/ISSUE_TEMPLATE ディレクトリを作り、その下に YAML ファイルを置く。 YAML ファイルのサンプルを公式ドキュメントから引用する。

name: Bug Report
description: File a bug report
title: "[Bug]: "
labels: [bug, triage]
assignees:
  - octocat
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report!
  - type: input
    id: contact
    attributes:
      label: Contact Details
      description: How can we get in touch with you if we need more info?
      placeholder: ex. email@example.com
    validations:
      required: false
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Also tell us, what did you expect to happen?
      placeholder: Tell us what you see!
      value: "A bug happened!"
    validations:
      required: true
  ...

トップレベルの name, description といったプロパティについては
Syntax for issue forms > Top-level syntax を参照。

メインとなるフォーム部分は body 内にフォーム要素の配列として定義する。
フォーム要素のプロパティについては
Syntax for GitHub's form schema を参照。

以下、個人的に気になったポイント。

表示できるフォーム要素のタイプ

現在は以下の5種類。

markdown
input
textarea
dropdown
checkboxes

markdown は文字通り Markdown で任意のメッセージを記載できるというものだが、これはフォーム上で表示されるだけで submit されない = 登録された issue には記載されない。

- type: markdown
  attributes:
    value: |
      `type: markdown` はフォームに表示されるがsubmitされない(登録されたissueには記載されない)。
      issue 登録者向けのメッセージとして使えそう。

f:id:dackdive:20210630003056p:plain

textarea に `render: <言語>` を指定するとコードブロックになる

textarea には render というプロパティがある（ドキュメント）。
render: javascript などのようにプログラミング言語を指定すると、結果がコードブロックとして表示され、指定した言語でシンタックスハイライトされるようになる。

- type: textarea
  id: textarea-2
  attributes:
    label: "Textarea (render: javascript)"
    description: "render: <言語> を指定するとコードブロックになり、指定した言語でシンタックスハイライトができる"
    render: javascript