不具合を切り分けて報告する

この手順でできること

この手順を終えると、必須の欄が埋まった Issue が1件立ちます。手順は5つです。切り分けないまま報告すると、FloatSoda の問題か、使い方か、環境かが分からず、直す人が再現に時間を使います。報告の形をそろえると、直るまでが早くなります。

自分のツールで FloatSoda を使っていて、おかしな挙動に出会った人が対象です。実機で動かした結果を報告したい人は、動作検証の結果を報告する場合に進みます。

前提条件

GitHub のアカウントを用意しておくこと
使っている FloatSoda のバージョン(NuGet パッケージのバージョン、または試したコミットの SHA)を確かめておくこと
不具合が出るコード、または再現の手順を用意しておくこと

再現できない場合は、うまくいかないときに進みます。

手順1: 利用者向けの切り分けを済ませる

使い方の誤りや環境の問題は、先に利用者向けのガイドで切り分けます。

反応しないときに切り分けるを読み、当てはまる原因を確かめる
利用者の環境で動かないときを読み、当てはまる原因を確かめる

できた? 使い方の誤りや環境の問題では、症状の説明がつかない。

できなかったら

リンク先の原因に当てはまったときは、そこに書かれた直し方を試します。直ったときは Issue を出す必要はありません。

手順2: 最小の再現に絞る

不具合が出るコードから、再現に関係しない部分を外して、小さなコードにします。外しても同じ症状が出るなら、外した部分は再現に要らないので、外したままにします。症状が出なくなったら、外した部分が原因に関わっています。

ウィジェットツリーから、子や兄弟のウィジェットを1つ外す
不具合がまだ出るかを確かめる
出なくなったら元に戻して、別の部分を外す
外せる部分がなくなるまで繰り返す

Issue テンプレートの「最小再現コード」の欄には、次の形のコードを貼ります。

app.CreateWindow(new DashboardWindow
{
    Title = "Repro",
    Child = new Padding
    {
        Spacing = EdgeInsets.All(8),
        Child = new Text("hello"),
    },
});

この例は、app の作成を省いた断片です。実際に貼るコードは、app の作成まで含めて、貼るだけで動く形にします。

できた? 貼り付けるだけで動くコードで、不具合が再現する。

できなかったら

コードでは再現できない場合は、Issue の同じ欄に再現の手順を文章で書きます。

手順3: Flutter でも起きるかを確かめる(Flutter 由来の場合)

不具合が Flutter 由来のウィジェットに関わるときは、Flutter でも同じことが起きるかを確かめます。FloatSoda は Flutter のウィジェットを移植しているので、起きた挙動は次の3つのどれかに分かれます。

FloatSoda のバグ
意図された Flutter の仕様
FloatSoda 固有の意図的な差異

Flutter でも同じことが起きた場合は、意図された仕様と決めつけず、Flutter の公式の説明やテストも確かめます。

この欄は任意です。分かる範囲で書き、分からなければ空欄にして出します。Flutter の元の実装を引く手順は、開発環境を用意するにあります。

手順4: バージョンと環境を集める

Issue に書く値を、次の表のとおりに書き出します。

値	調べ方
FloatSoda のバージョン	NuGet パッケージのバージョン、または試したコミットの SHA
.NET SDK のバージョン	`dotnet --version` の出力
OS	例: Windows 11 26200
GPU とドライバ、HMD、SteamVR のバージョン	表示や描画の問題のときだけ

手順5: Issue を出す

Bug report のテンプレートを開いて、欄を埋めて出します。必須の欄だけ埋めれば足ります。

必須の欄と任意の欄は、テンプレートの .github/ISSUE_TEMPLATE/bug_report.yml に書かれています。「最小再現コード / 再現手順」には手順2で絞ったコードを、バージョンと OS の欄には手順4の値を、「Flutter との対応」には手順3で分かったことを書きます。

例外が出たときは、手元のパスや個人情報を伏せたうえで、「例外 / スタックトレース」の欄に全文を貼ります。

タイトルには、何をする Issue かを書きます。種別や領域はラベルで表すので、feat(Widget): のような prefix は付けません。

Issue は公開されます。出す前に、手元のパスや個人情報が貼り付けに入っていないかを確かめます。

できた? Issue が立ち、bug のラベルが付いている。

できなかったら

ラベルが付かなかった場合は、テンプレートを使わずに作った可能性があります。作成済みの Issue のコメントで、bug ラベルの付与を頼みます。同じ報告を作り直すと、重複した Issue ができます。

自分で直したい場合は、ブランチ名と PR の範囲をコントリビューターの規約で確かめます。

動作検証の結果を報告する場合

実機で試した結果は、サンプルの checks/results/ に jsonl で足す PR を出して報告します。「落ちた」「落ちなかった」と、HMD、GPU、プラットフォーム、モード、日付を同じ形で残します。ここでの「落ちなかった」は、作例の確かめる点をすべて通ったことを指します。落ちなかった記録も、その環境で動いた証拠になります。

ファイル名と1行の形式は、CONTRIBUTING.md のサンプルを追加する場合の規約に定められています。このページには写していないので、PR を出す前に開いてください。項目ごとの手順は、floatsoda-device-test-run に書かれています。

うまくいかないとき

再現できないとき、または FloatSoda の問題か判断できないときの行き先は、次のとおりです。

状況	行き先
使い方の誤りかもしれない	手順1の2ページ
再現しないが、おかしな挙動を見た	見た状況と環境を書いて Issue を出す
判断がつかない	判断がつかないことを Issue に書いて出す