現在、GitHub の Issue を GitHub Projects を利用して4つのプロジェクトに分類しつつ管理しています。
baserCMSの既存機能の移行に関するIssue
既存機能の移行に際して発生したユニットテストとAPI開発のためのIssue
baserCMS5の新機能のIssue
上記に当てはまらず、マイルストーンが決定していないIssue
GitHub Projects で Issueを作成すると、どのレポジトリにも紐付いていない、「draft」という状態になります。この時点では、プルリクエストとは紐付ける事ができません。
新しいIssue は、まず、draft として作成しておきます。
そして、「どうするか」が決定したら、レポジトリに紐付いた Issueに変換します。
draft のタイトルをクリックして詳細画面を開きます。
「Convert to issue」 をクリックします。
このプロジェクトでは、主に、新しく作成したメソッドや、既存メソッドで動作確認済(@checked)、残作業なし(@noTodo)となっているもののユニットテストの Issue を管理します。
Issue には、ユニットテストが実装できるようにするため、説明欄に指示を書く事を前提とします。
draft から Issueに変換する際には、次を設定してください。
現在、ユニットテストの指示について、メソッドのヘッダーコメントに仕様の詳細を記述した上で、それを確認する事を指示としています。
Issue への変換時には、メソッドのヘッダーコメントを見直した上で、Issueの説明欄に「メソッドのヘッダーコメントを確認する」と記載ください。
なお、メソッドのヘッダーコメントについては、後に自動でAPIリファレンス化する予定としています。
ヘルパは、baserCMSのユーザー(制作者)が利用する前提ですので、細かく書いた方がいいですが、それ以外については、特に注意すべき点や特殊な仕様がある場合に書くようにしましょう。
本来はif文の分岐を全部をユニットテストで通すのが良いとされていますので、その全てについて、ヘッダーコメントに記載されいている事が望ましいですが、ユニットテストを実装するにあたり必要な情報が記載されていればOKとします。
また、ヘルパーの @param は参照される頻度が高いので何のパラメータなのかも書きます。
// 例)
/**
* @param int $id コメントID
*/
なお、コメントの記述については、マイグレーション方針のコメントヘッダー を参考にしてください。
作業担当者は、「Instructed」ラベルのついた Issue より作業に取り掛かります。