決定を ADR に書く

この手順でできること

議論で決まった内容を、あとから「なぜそう決めたか」を読める形で ADR(Architecture Decision Record、設計の決定の記録)に書けます。手順が終わると、ADR が1本、置き場所にある状態になります。ADR には、背景、決定、理由、影響が書かれます。Flutter との差異なら、差異の記録に必要な5項目も書かれます。

決定の理由が議論のコメントにしかないと、あとから「なぜこうなっているか」を追えません。同じ議論も繰り返されます。ADR は、その理由を repo に残すための記録です。ADR の正本は repo に置きます。

手順は5つです。

ADR に書く決定かを確かめる
番号と置き場所を決める
背景・決定・理由・影響を書く
Flutter との差異なら、5項目を足す
PR で出す

議論の結論が出ていない場合は、先に提案を書くへ戻ってください。

前提条件

次の2つがそろっていれば、手順1から始められます。

決まった内容と、議論の Issue を確認しておくこと
提案の書き方と規約を読んでおくこと(提案を書く、コントリビューターの規約)

手順1: ADR に書く決定かを確かめる

次のような決定は、ADR に書きます。

設計判断
依存やプロジェクト構成の決定
Flutter との差異
public API の方針

typo の修正のように、設計判断のない変更は書きません。迷ったら書いてください。Issue が必須な変更(CONTRIBUTING.md の「Issue が必須な変更」)のうち、設計判断を伴うものが目安です。

できた? 「書く」「書かない」のどちらかを、理由とあわせて言えます。書くなら手順2へ進みます。

手順2: 番号と置き場所を決める

ADR の置き場所と番号の付け方は、まだ決まっていません。決まるまでは、ADR を足す前に、議論の Issue で置き場所をたずねてください。

今ある Flutter との差異は、差異の台帳 known-divergences.md に記録されています。入口は決定の記録(ADR)の一覧です。

できた? 置き場所と番号が、Issue で確認できています。

手順3: 背景・決定・理由・影響を書く

ADR には、次の4つの欄を書きます。

欄	書くこと
背景	決める前の状況
決定	選んだもの
理由	選ばなかった案と、選んだ理由
影響	決めたことで生じる制約や代償

議論の記録を見ながら、欄ごとに書きます。

できた? 理由の欄に、実際に検討した案と選んだ理由が書かれています。別の案を検討していない場合は、その旨が書かれています。

手順4: Flutter との差異なら、5項目を足す

Flutter と違う設計の決定には、記録必須の5項目を書きます。5項目の内容は、REVIEW.md の「6. Flutter parity」にあります。このページには写しません。5項目を背景・決定・理由・影響のどの欄に書くかは、決めていません。

差異を固定するテストがない差異は、次の移植で戻されます。テストの名前を必ず書いてください。利用者に見える差異は、利用者向けの docs にも書きます。

差異の台帳 known-divergences.md に同じ差異のエントリがあるときは、重複させないでください。どちらを正にするかを、Issue でオーナーに確かめます。台帳を ADR にまとめる移行は、まだ決まっていません。

できた? 5項目がすべて埋まり、テストが実在します。

手順5: PR で出す

PR には ADR の追加だけを入れます。関連する Issue は、PR 本文の「Related Issue」欄に #NN の形で結び付けます。この PR だけで Issue の完了条件を満たすときは、Closes #NN と書きます。出したあとの指摘への対応はレビューの指摘を受けて直すに進んでください。

ADR を読むとき

「なぜこう作ったのか」を調べるときは、ADR の4つの欄を上から読みます。背景で当時の状況を、決定で選んだものを、理由で選ばなかった案を確かめます。ADR の置き場所と番号の付け方は、決まっていません。Flutter との差異は、差異の台帳 known-divergences.md で探します。入口は決定の記録(ADR)の一覧にあります。

うまくいかないとき

何が決定か分からない、または決定がまだない

提案を書くに戻り、議論の結論を Issue にまとめてください。