決定の記録(ADR)の一覧

ADR とは何か、台帳とは何か

このページは、「なぜこの形に作ったのか」「Flutter とどこをわざと変えたのか」を調べる人が、記録を探すための入口です。記録の書き方は、このページには置きません。書き方は 決定を ADR に書く にあります。

FloatSoda には、決定を残す記録が2種類あります。

• ADR: 設計や規約を決めた理由と、選ばなかった案を残す記録
• 台帳: Flutter との差異を項目ごとに残す記録

台帳のファイルは known-divergences.md です。意図した差異の一次情報として扱うのは、deliberate の項目だけです。

調べたいことで見分けます。「なぜこう作ったのか」は ADR、「Flutter とどこが違うのか」は台帳です。

ステータスと種別の意味

一覧の列で使う言葉を、先に定義します。

ADR のステータスは、次の5つを候補としています。正式に採用するかは未決です。

ステータス	意味
proposed	提案中。承認されるまで、決定として扱わない
accepted	承認済み。決定として扱う
superseded	後の決定に置き換わった
rejected	却下された
deprecated	決定は残るが、もう使わない

一覧の種別は、次の2つです。

種別	内容
設計判断	設計や構成の決定。理由と別案を残す
Flutter との差異	Flutter と挙動を変えた決定。台帳のラベルも示す

台帳のラベルは、次の4つです。意図した差異の一次情報になるのは、deliberate だけです。

ラベル	意味
deliberate	意図した差異。設計判断として確定している。レビューは、これを一次情報として扱う
not ported	未移植。Issue を立てて追う
port mistake	実装されているが誤り。直す対象
unlabelled	まだ判断が下っていない。意図が確定していないので、一次情報として扱わない

決定の一覧

ADR の置き場所と番号の付け方は、決まっていません。一覧は、置き場所と番号が決まってから、1件につき1行で作ります。一覧の列は、番号、題名、種別、ステータス、決定日、関係するページです(追跡: #219)。それまでの Flutter との差異は、次の節の台帳で探します。

該当する決定が見つからない場合は、まだ決定されていないか、記録されていません。決めたい内容があれば、提案を書く に進みます。

Flutter との差異の台帳

Flutter のコードを移植している人、移植されたコードをレビューしている人は、自分が扱うウィジェットに関わる差異がないかを、台帳で探します。層の解説の「Flutter と違うところ」(フレームワーク層)からも、台帳の項目を参照しています。

台帳の項目は、次の欄を持ちます。

欄	内容
FloatSoda	FloatSoda の挙動。ソースの場所つき
Flutter	Flutter の挙動。対応するファイルつき
Why	差異が必要な理由
Test	差異を固定するテスト
Docs	利用者向けの docs
Observation	差異が観測できる場所(HEADLESS か VR)
Label	上の4つのラベル

意図した差異には、次の5項目の記録が必須です(REVIEW.md の「Flutter parity」)。Flutter の挙動、FloatSoda の挙動、差異が必要な理由、差異を固定するテスト、利用者に影響する場合のドキュメントです。レビューは、台帳の項目の番号(たとえば 2 番)で、項目を参照します。台帳の項目を移すときは、番号を変えません。

台帳に項目がなく、新しく差異を作りたいときは、Flutter から移植する と 決定を ADR に書く に進みます。

決定を足すとき

新しい決定を記録したいときは、決定を ADR に書く に進みます。