チェンジログの項目になる機能要望テンプレート

機能要望テンプレートとは、四つの質問からなるフォームだ。その人が何をしようとしているか、何がそれを阻んでいるか、代わりに何を試したか、そして完了したときにどう知らされたいか。それ以外によく見られるもの、つまり優先度の選択肢、工数の見積もり、ビジネス価値のスコアなどは、依頼を受け取るチームのためのものであり、送る側の人はそれを間違って埋めることになる。

整った依頼はテンプレートの正しいテストではない。正しいテストはこうだ。六か月後、その機能が出荷されたとき、誰かがその依頼を見つけ、理解し、それを書いた人に伝えられるか。ほとんどのテンプレートは受付のために設計されている。これはループが閉じる日のために設計されている。

機能要望テンプレートには何を含めるべきか

目標、障害、回避策、そして依頼者へと戻る道を含めるべきだ。その順番で四つのフィールドがあり、それぞれが後でチームが尋ねることになる問いに答えている。

意図的に含まれていないもの：必須フィールドとしての提案された解決策（コメントとしては歓迎だが、枠組みとしては間違っている）、優先度の選択肢（すべての投稿者が「高」を選ぶ）、そして工数や価値の見積もり（それはトリアージ後のチームの仕事だ）。解決策を尋ねるテンプレートはボタンについての依頼を集め、目標を尋ねるテンプレートは成果についての依頼を集める。そして成果こそが、チェンジログの項目が書かれる対象だ。

テンプレート

これは私たちが使っているGitHub issueテンプレートをフォームとして示したものだ。.github/ISSUE_TEMPLATE/feature_request.ymlに貼り付ければ、New Issueページで構造化されたフォームとしてレンダリングされる。これを通じてファイルされた依頼は、フィードバックウィジェットからファイルされたものと同じフィールドを持つissueとして着地し、それが次のセクションで重要になる。

name: Feature request
description: What you are trying to do, and what stops you.
labels: ["feature-request"]
body:
  - type: textarea
    id: goal
    attributes:
      label: What are you trying to do?
      description: >-
        The outcome, not the button. "Export a month of invoices as one
        PDF" beats "add a PDF export".
    validations:
      required: true
  - type: textarea
    id: blocker
    attributes:
      label: What stops you today?
      description: >-
        Where the product runs out. An error, a missing option, a limit.
    validations:
      required: true
  - type: textarea
    id: workaround
    attributes:
      label: What do you do instead?
      description: >-
        The spreadsheet, the script, the manual step. "Nothing, I gave
        up" is a valid answer.
  - type: input
    id: contact
    attributes:
      label: How should we tell you when it ships?
      description: >-
        An email address, or leave blank to be notified only on this
        issue.

二つの詳細が仕事をしている。labels: ["feature-request"]は、誰かがトリアージするのを待つのではなく、作成時点で依頼が分類されることを意味する。そして最後のフィールドが存在するのは、「お知らせします」が約束であり、約束には宛先が必要だからだ。

機能要望はどんなラベルを持つべきか

機能要望は、それが何であるかを示すラベル、どれほど緊急かを示すラベル、そしてどこから来たかを示すラベルを一つずつ持つべきだ。三つのラベル、三つの軸、それぞれが異なる読み手によって読まれる。

ウィジェットは投稿をissueとしてファイルする際に、最初の二つの軸とfrom-widgetを適用する。from-formとfrom-supportは、それ以外の経路で届く依頼のための提案だ。ウィジェットのラベルは、種類（bugかfeature-requestかは、メッセージだけから分類器が判断する）、優先度（落ち着いた具体的なクラッシュレポートは高、すでに尋ねられたものの重複は低、セキュリティ問題を少しでも示唆するものは言い回しにかかわらずbugかつ高)、そしてfrom-widgetだ。同じ三つの軸は、上記のテンプレートを通じて手作業で届く依頼にも同様に機能する。それこそが要点だ。依頼はどこから入ってきても依頼であるということだ。

もう一つの慣習がある。ウィジェットは、投稿者のメールアドレスをissue本文から取り除いてからファイルする。issueは公開されている可能性のあるリポジトリの中にあるからだ。代わりに投稿の参照番号が入る。アドレスはissueに入らず、投稿者は結果をウィジェットそのもので追う。あなたのトラッカーがチーム外から見える場合は、連絡先フィールドについても同じことをしよう。

機能要望はどのようにチェンジログの項目になるか

機能要望がチェンジログの項目になるのは、pull requestがそのissueをクローズし、そのpull requestから下書きされた項目がそこへリンクし返すときだ。仕組みはGitHub自身のクローズキーワードだ。説明にFixes #142と書かれたPRは、マージ時にissue 142をクローズする。チェンジログの項目がマージされたpull requestから下書きされているなら、その下書きはissue番号を一緒に運ぶことができ、項目は誰が依頼したかを知っている。

それが、テンプレートが解決策ではなく目標を尋ねる理由だ。項目が書かれるとき、目標こそが書き手が必要とする文になる。「請求書を一か月分まとめて一つのPDFとしてエクスポートできるようになりました」はチェンジログの項目だ。「PDFエクスポートを追加」はコミットメッセージだ。pull requestから下書きするチェンジログツールは収集とリンクを担えるが、言い回しには依然として人間が必要であり、その人間には目標が必要だ。

出荷されたとき何が起きるか

依頼者には、項目へのリンク付きで知らされる。私たちの仕組みでは、ウィジェットから届いた依頼についてはそれが自動で行われる。人間がその項目を承認した後にissueに投稿される「Shipped — <項目のタイトル>」というコメントであり、公開された項目へのリンクを持つ。同時に、ウィジェットは投稿者に同じ項目を表示する。このテンプレートから手でファイルされたissueには自動のコメントは付かないので、同じルールに従って自分でそのループを閉じよう。コメントがマージ時ではなく承認時に投稿されるのは意図的だ。何かがまだ公開されていないうちにそれが公開されていると述べるコメントは、タイムスタンプ付きの破られた約束になるからだ。それぞれの依頼は多くとも一度だけ通知される。同じ項目を二度承認しても、二つ目のコメントは生まれない。

これを手作業で行うなら、ルールは同じだ。pull requestの時点でループを閉じてはいけない。公開された項目からループを閉じ、それを一度だけにしよう。フィードとウィジェットは同じ項目を、依頼していなかったほとんどの人々に運ぶ。コメントは依頼した本人のためのものだ。

なぜほとんどの機能要望テンプレートは失敗するのか

それらはトリアージを楽にするために設計されており、それには成功しているが、依頼者にとって唯一重要な瞬間を犠牲にしている。十二個のフィールドを持つテンプレートは依頼の数が減り、集まる依頼は十二個のフィールドを埋める忍耐を持つ人々からのものになる。それは機能を必要としている人々とは同じ集団ではない。四つのフィールドを持ち、そのうちの一つが「どう連絡すればよいか」であるテンプレートは、より多くの依頼を集め、そのすべてに応えることができる。

FAQ

機能要望テンプレートは優先度を尋ねるべきか? いいえ。代わりに回避策を尋ねよう。「毎週金曜日にスプレッドシートにエクスポートして手で入力し直しています」は、投稿者が「高」に設定したドロップダウンよりも優先度について多くを語る。

依頼者は解決策を提案すべきか? 自由記述の中でならできる。それを枠組みにしてはいけない。解決策として書かれた依頼は、互いにマージしにくく、それについてチェンジログの項目を書くのも難しくなる。

機能要望は公開ロードマップに載るべきか? 計画されたら、そうすべきだ。同じissueへのラベルがそれを「計画済み」の列に置き、依頼者はそれが動くのを見ることができる。公開ロードマップの記事がその仕組みだ。

重複はどう扱えばよいか? 新しい依頼を既存のissueにリンクし、低優先度のラベルを付けよう。クローズしてはいけない。それぞれの重複は、出荷されたときに伝えるべきもう一人だ。Changeloopの自動コメントでは、pull requestがその人のissueも指定している場合（Fixes #142, fixes #187）にだけ、その人に伝わる。

テンプレートはどこに置くべきか? pull requestを受け取ることになるリポジトリの中だ。そうすればクローズキーワードが機能する。別のトラッカーにある依頼はマージ時に手作業でリンクしなければならず、そのステップこそが省略されがちなものだ。

この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。

changeloopの関連ページ： 開発者向けドキュメント, changelogツール比較