提案を書く
この手順でできること
Section titled “この手順でできること”新しい機能や設計の変更を、議論に入れる形で Issue に書けます。手順が終わると、提案の Issue が1件立っている状態になります。Issue には、提案が受け入れ範囲に入ること、どの利用者のどんな困りごとを解くか、Flutter と違うならその理由が書かれています。
受け入れ範囲の外の提案や、理由の書かれていない提案は、議論に入る前に止まります。必要な情報を先に書くと、議論を設計の中身に使えます。
手順は5つです。
- 似た議論を探す
- 受け入れ範囲に入るか確かめる
- 利用者のペルソナに照らして、困りごとを書く
- Flutter と違う設計なら、差異の5項目を書く
- Issue を出す
提案が通ったあとに決定を記録する手順は、決定を ADR に書く にあります。
- GitHub のアカウントを用意しておくこと
- FloatSoda が大事にしていることを読んでおくことが望ましい
- Issue・PR・マイルストーンの読み方を読んでおくことが望ましい
後ろの2つを読んでおくと、手順1から迷わず進められます。
手順1: 似た議論を探す
Section titled “手順1: 似た議論を探す”案のキーワードで、Issue と PR を検索します。閉じた Issue も見てください。古い Issue だけを根拠に決めないでください。Issue が書かれた時点の前提が、今も成り立つとは限りません。
できた? 似た議論が「ある」か「ない」かを言えます。ない場合と、あっても新しい論点がある場合は、手順2へ進みます。
手順2: 受け入れ範囲に入るか確かめる
Section titled “手順2: 受け入れ範囲に入るか確かめる”現段階のコアが受け入れるのは、Flutter の widgets/basic.dart に相当するプリミティブ層のウィジェットです。単一の RenderObject への薄いラッパーで、状態やビジネスロジックを持たないものを指します。Button や Card のような装飾済み・複合ウィジェットや、Material / Cupertino 相当のコンポーネントは受け入れません。範囲外の提案は、コア以外の別パッケージやユーザーランドでの実装を検討してください。
新しい public API は、さらに受け入れ条件があります。合否基準は、更新後の docs だけを読んだ LLM が、その API を正しく使えるかです。
範囲の正本は CONTRIBUTING.md の「受け入れ範囲」と「新しい public API を追加する場合の受け入れ条件」です(コントリビューターの規約 から案内しています)。
できた? 「入る」「入らない」「迷う」のどれかを言えます。迷うときは、Issue で相談してください。
手順3: 利用者のペルソナに照らして、困りごとを書く
Section titled “手順3: 利用者のペルソナに照らして、困りごとを書く”FloatSoda が想定する作り手は3種類です(AGENTS.md の「Target Users」)。
| ペルソナ | 特徴 |
|---|---|
| LLM にコードを書かせる VRChatter | 自分ではほとんどコードを書かず、LLM に docs と API を読ませる |
| Booth でオーバーレイを売るクリエイター | Unity のプログラマー。uGUI しか知らず、宣言的 UI は初めて |
| uGUI を避けたいエンジニア | シーンやプレハブが diff やレビューに向かないことが悩み |
提案は、3種類のどれの困りごとを解くかで説明します。書くのは次の3点です。
- だれの
- どんな困りごとを
- この提案がどう解くか
外部のアセットや設定ファイルのように、コードに書けない状態を入れる提案は、トレードオフを検討してから書いてください。UI のすべてを C# のコードに書けることが、FloatSoda の見せ場だからです。
できた? ペルソナを1つ挙げて、その人の困りごとを一文で言えます。Flutter 由来の部品で、Flutter と違う設計にするなら手順4へ、そうでなければ手順5へ進みます。
手順4: Flutter と違う設計なら、差異の5項目を書く
Section titled “手順4: Flutter と違う設計なら、差異の5項目を書く”Flutter と違う設計にするときは、記録必須の5項目を、分かる範囲で書きます(REVIEW.md の「6. Flutter parity」)。
- Flutter の挙動
- FloatSoda の挙動
- 差異が必要な理由
- 差異を固定するテスト
- 利用者に影響する場合のドキュメント
提案の段階でまだ存在しない項目(差異を固定するテスト、docs の更新)は「計画」と書きます。名前やリンクは、実在するものにだけ付けます。
「実装しやすい」「こちらの方が安全」「こちらの方が自然」だけでは、差異の理由になりません。Flutter の元の実装の読み方は Flutter から移植する にあります。提案が通ったら、決定を 決定を ADR に書く で記録します。
できた? 差異が必要な理由を、制約や利用者の困りごとと結び付けて説明できます。
手順5: Issue を出す
Section titled “手順5: Issue を出す”機能要望のテンプレート .github/ISSUE_TEMPLATE/feature_request.yml に書いて出します。欄の一覧と必須の別は、テンプレートを開いて確かめます。「動機 / ユースケース」には手順3の3点を、「対応する Flutter API」には手順4の Flutter 側の情報を書きます。
種別ラベルは、機能要望のテンプレートが feature を付けます。Flutter と違う設計なら、flutter-divergence も必要です。ラベルを付ける権限がない場合は、付けたいラベルを Issue に書いて頼みます。public API や observable behavior を変える提案は、breaking change の有無も Issue に書いてください。Alpha であることは、判定を省略する理由になりません。
できた? Issue が立ち、種別ラベルが1つ付いています。
議論で決まったら、決定を ADR に書く に進んでください。
うまくいかないとき
Section titled “うまくいかないとき”範囲外と言われた
コア以外の別パッケージやユーザーランドでの実装を検討してください。
理由が足りないと言われた
手順3と手順4に戻り、困りごとの3点と、差異の5項目を書き足してください。