私が輝く、夏がはじまる。
私が輝く、夏がはじまる。

チケットの正しい書き方!Pull Requestの発行の仕方も解説

おきく

どうも! テクニカルディレクターのおきくです。

本日は、普段BiTT事業で実際にCODYメンバーに実施しているGitHubやAsanaを使ったディレクション方法についてまとめました。この記事が少しでも皆さんの参考になれば嬉しいです。

ここでお話する内容は、自分のGitHubプロジェクトにもなりますが、以下GitHubのリポジトリにフォーマットとしてまとめています。もしよければこちらも参考にしてください。

チケットの書き方のポイント(エンハンスメント、新規機能作成時)

フォーマットはこちらから。

ポイント① 1チケット = 1PRの粒度でまとめましょう

これは世界共通のルールなので、いわずもがなでしょうか。基本はグローバルスタンダードなルールに則って行いましょう。

ポイント② 概要をしっかりとまとめましょう

メンバーに何のためにどうしてこのチケットが発行されているのか、どんなタスクなのか全容がわかるように概要をまとめましょう。これを行うことにより、チケットの全体イメージをメンバーに共有することが可能となるのではないでしょうか。

ポイント③ 終了条件をしっかりとまとめましょう

何ができたらこのチケットが完了なのかを明確に記載しましょう。これを書くことによって、PR時にレビューアーは、チケットで要求された内容をすべて満たしているのかがわかるようになります。特に以下の通りMarkdownのcheckbox機能も用意してあげると、エンジニア側としてのチェックリスト機能としても活用することも可能にもなるります。ぜひ活用してみてください。

またフロントエンドで画面を新規作成する場合は以下のようなすべての画面の仕様を明記してあげると、メンバーに画面仕様を伝えることも可能にもなります。

画面デザイン内容

自分が経験したプロジェクトではデザイナーが作成したXDのURLを共有したり、スクショを貼り付けたりしています。CODYメンバーがデザインのCSSや日本語をコピペできるようにするために、主にXDのリンク先を共有することが多いです。

各種イベント発生時の挙動を記載

例えばボタン押下したときにどういった挙動をするのか、画面ローディング時はどんなアクションが発生するかなど、ユーザー操作によって発生しうるシステムフローをまとめるようにしましょう。

API Parameterと画面項目との紐付け

例えば画面を開く場合にAPIを使ってGet Methodを実行する場合は、Response Parameterとして応答が返ってきます。しかし、取得したパラメータがどの項目と紐づくのか、はたまたSubmitする際は、PostもしくはPutを実行します。Request Parameterがどの項目と紐づいているかなど、表形式で纏めてあげるとエンジニアとしては画面設計書相当の内容をInputされるので実装のイメージも湧くのではないでしょうか。

GitHubの場合はmarkdownが使えるので、markdown形式で以下の通り関連図を作ると親切かなと思います。

例外やエラー発生時の挙動

この当たりは見落としがちにはなるので、しっかりと明記することで漏れを防止することにもつながります。

エンジニアが実施するべきテスト内容も記載しましょう

自分の場合は作成したテスト計画に基づいて、各自のテストのロールを決めるようにしています。エンジニアが行うべき主なテストは単体テストレベルになるので、自分はテクニカルディレクターとして、エンジニアにどこまでテストを実施してほしいかについても、終了条件に含めるようにしています。

そしてエンジニアからPull Requestが発効された場合は、outputとして試験の実施を確認するようにしてます(もし試験実施をしていない場合は、差し戻しをするようにもしてます)。

これは参考ですが、実施するべきテストのフォーマットもリポジトリに用意しています。URLはこちらから。

チケットの書き方のポイント(不具合改修依頼)

フォーマットはこちらから。

ポイント① 発生条件の明記

エンジニアの人から見て、気持ちよく作業ができるようにするためにも、不具合チケットを作成する場合は、端的にわかりやすく再現できるように以下をまとめるようにしています。

  • 発生ソフトウェアバージョン
  • 発生デバイス
  • 発生手順
  • 問題発生時のスクショやムービー

エンジニアにとって、不具合を指摘するということは、責められていると思ったり、責任を感じる部分もあるため、心理的なストレスやダメージは大きくなります。不具合チケットを作成する場合は丁寧かつ慎重に行う必要があります。

ポイント② 終了条件の明記

記載するべき内容は、エンジニアにやってほしいこと、ゴールについて明記することになります。特に大事になる部分はテストをどこまでやってほしいかについてです。修正インパクトが大きい場合のレグレッションテストの工数は大きく跳ね上がります。

基本はテスト計画に基づいて、各メンバーのロールを決定することになりますが、チケット発行者としてエンジニアに対して、どこまで試験を実施してもらうかについては、チケットを発行するタイミングで明記することが大事になります。

Pull Requestの発行の仕方

若干チケットの趣旨とは異なるかもしれませんが、Pull Requestチケットの書き方についても書きたいと思います。

フォーマットはこちらから。

ポイント① 対象のチケット番号を記載しよう

対象のチケット番号をPull Requestチケットに記載しましょう。特にGitHubですが、チケット番号を記載することで、Pull requestとチケットがLinkingされます。

そのため、後になってこのPull Requestと紐づいているチケットや、逆にこのチケットと紐づいているPull Requestが何かについてトレースができるようになります。このコミットがどういった経緯でなぜこのように決まったかについて、あとで見れるようにするためにも、Pull RequestとチケットをLinking設定することを推奨します。

ポイント② 実施した試験について記載しよう

チケットの書き方でも記載しましたが、各チケットでの大前提はエンジニアも試験を行うことです。そのため、エンジニアがどんな試験を実施したか記載させるようにしましょう。これにより、レビューアーとしては足りていない試験があれば、試験実施を促すことにもつながります。

ポイント③ 特記事項

何かレビューアーに伝えておきたいことがあれば、特記事項や制限事項としてまとめておきましょう。

最後に

チケットの作成はメンバーへのディレクションのみならず、エンジニアとディレクターとのコミュニケーションツールでもあり、ログ機能という位置付けにもできます。これを上手く活用することで、システムのトレーサビリティーやメンテナンス性並びに品質向上にもつながるため、丁寧にしっかりと運用されることを推奨いたします。

最後までご覧になっていただきありがとうございました。

3 0 0 0