ククログ

株式会社クリアコード > ククログ > OSSプロジェクトへのコントリビュートで避けるべき6つのこと:4. 既知の問題や解決策がある事について報告しない

OSSプロジェクトへのコントリビュートで避けるべき6つのこと:4. 既知の問題や解決策がある事について報告しない

結城です。

OSSプロジェクトへのコントリビュートの「べからず集」記事について、まだ要領を掴めていない人が「自分のしようとしていることもそれにあてはまるのではないか?」と心配になってコントリビュートをためらうことがないように、具体的な例と考え方を紹介するシリーズの4本目です。前回(3回目)前前回(2回目)に続き、今回は4つ目の「べからず」として挙げられている、既知の問題や解決策がある事について報告しないという話について説明します。

4. 既知の問題や解決策がある事について報告しない(報告する前に、既存の報告や情報がないか探す)

筆者はOSSへの障害報告について、以下の2種類の声をたびたび観測しています。

  • 問題を報告してほしい! 報告がないと、問題の存在を把握できなくて困る!

  • 同じ問題を何度も報告しないでほしい! 重複する問題の報告が多すぎて困る!

一人のプロジェクトオーナーとしては、どちらの気持ちも分かりすぎるくらいに分かるのですが、単純にこのようにそれぞれの声を並べてしまうと、報告しようかどうしようかと迷っている人は、ダブルバインド1の状態になってしまいます。

なので、この記事では、自分が遭遇した問題を報告してみようと思った人のために、「問題を報告する前に何を(どこを)調べればいいのか」「どこまで調べれば、充分に調べたと言っていいのか」を解説してみます。

困ったときは、まず検索

何はともあれ最初に試みてほしいのは、GoogleDuckDuckGoなどの一般的な検索サービスで、困っている内容を検索してみるということです。OSSプロジェクトのイシュートラッカーを見てみるのは、Web検索でそれらしい情報を得られなかった後からで充分です。

これは、初級者から上級者まであらゆる人の場合に言えることです。上級者の場合でも、自分が遭遇したトラブルについて「これは不具合に違いない、自分が使い方を間違えるわけがない」と思い込んで、いきなりソースコードを調べてみたものの、よくよく調べてみたら単に使い方を間違えていただけだと分かった、というオチになることはよくあります。

検索するときのポイントは、以下の情報を含めることです。

  • 問題が起こる場面でのOSの種類とバージョン、アプリケーション名とバージョン。例:

    • Windows 10 Pro 1909

    • Firefox 82.0.2

  • 問題が起こる場面でした操作に関わる、コマンド列や機能名。例:

    • terraform apply auto-approve(コマンド列とその引数。「-」で始まるフレーズは、検索エンジンによっては「その語を含まない」という意味に解釈されることがあるので、コマンドラインオプションの先頭の「-」は検索語句から外すのが安全。)

    • ファイル 新規作成 既存のメールアカウント(Thunderbirdのメニュー項目の場合。)

    • ip_configuration(変更した設定項目の名前)

  • 問題の発生時に画面上に現れているメッセージ。例:

    • check_is_installed_by_gem is not implemented in Specinfra::Command::Windows::Base::Package(端末上に表示されるエラー出力)

    • このユーザー名とサーバー名のアカウントがすでに存在します。別のユーザー名またはサーバー名を入力してください。(ダイアログに表示されたメッセージ)

  • その他、起こっている症状を説明する表現。例:

    • 動かない(英語ではdoes not workcannot work

    • 開かない(英語ではdoes not openis not openedcannot openなど)

    • エラー(英語ではerror

ブログ記事やSNS上の投稿2なども含めて、日本語で情報が見つからない場合でも、英語で検索してみるとあっさり答えが見つかることがあります。これは、英語の使用人口は日本語の使用人口より圧倒的に多いので、その分はるかに多くの情報が出回っているからです。英語での表現が分からなければ、Google翻訳DeepL翻訳などの機械翻訳にかけた結果の文を検索してみてもいいでしょう。

当然、見つかった英語の情報を読むときも機械翻訳は有用です。近年では機械翻訳の精度の向上が著しいので、機械翻訳の結果をざっと見るだけでも、必要充分な情報を読み取れる場合が多いです。

既存の報告は、どのくらい探せば充分か?

一度の検索で思うような検索結果を得られなかった場合、検索フレーズを変えて何度か検索し直してみる3のが常道です。

  • キーワードを類語に入れ換えてみる。例:

    • 開けないインポートできない

    • ボタンが反応しないボタンが無効化されている

  • バージョン情報やベンダー名など、重要度が低いと思われる部分を省略してみる。例:

    • Windows 10 Pro 1909Windows 10 1909Windows 10

    • Mozilla Firefox 82.0.2Firefox 82.0.2Firefox

  • 表示されたエラーメッセージの中で、自分の場合に特有と思われる部分を削除してみる。例:

    • check_is_installed_by_gem is not implemented in Specinfra::Command::Windows::Base::Packagecheck_is_installed_by_gem is not implemented inis not implemented in

ただ、このような試みは、やろうと思えばいくらでもできてしまいます。探している情報が「ある」ことは、一度見つけられれば証明できますが、「ない」ことは証明できません。下手をすれば、存在しない情報を永遠に探し求め続けることにもなり得ます。そうならないためには、「ここまで探したんだからもう見つからない」と諦める判断を下す基準を決めておくのが大事です。

筆者の場合、OSSのトラブルに関する調査では、「自分に思いつく限りの表現で既存の報告を検索してみて、自分の得意分野では10~20分程度、不慣れな分野では30分~1時間程度の間にそれらしい情報が見つからなければ、まだ誰にも報告されていない問題である可能性が高い」と判断するようにしています。疑わしい既存の報告がたくさん見つかった場合は、それぞれの精査にもう少し時間を使うこともあります。いずれにしても、筆者の場合は1時間以上の時間をかけることは希です4

「重複する報告」や「場違いな報告」を恐れないで!

「Web全体を検索してもそれらしい情報が見つからず、イシュートラッカーのイシュー一覧にもそれらしい報告が見当たらない」という場合には、いよいよ報告のタイミングです。

(なお、「イシュートラッカーに報告するべきか、それともフォーラムでまず聞いてみるべきか」で悩む場合は、それぞれの使い分けを解説する過去記事を先にご覧ください。ここでは、イシュートラッカーに報告する場合と仮定します。)

ただ、「すでに他の人が報告しているにもかかわらず、自分の探し方が下手なだけで、既存の報告を見つけられていないだけかもしれない」と不安に感じて報告をためらってしまう人もいるかもしれません。

そのような場合、前項までで述べたような探し方をもうすでにした後であれば、思い切ってあなたの言葉で新しい報告としてフィードバックすることを、筆者はおすすめします。なぜなら、遭遇した場面や発生時の状況、報告する人の主観によって、同じ問題でも報告の表現の仕方はそれぞれ変わってくるからです。

違う言葉でされた報告は見つからないことがある

同じ原因の問題に関する報告がすでになされていた場合、基本的には後からフィードバックされた方に「重複する報告だ」と印が付けられ、既存の報告へと誘導するような情報が、プロジェクト運営者によって付けられます。

そんな場合でも、「ああ、自分の探し方が悪かったせいで見つけられなかったんだ」なんて恥ずかしく思う必要はありません。何故なら、あなたがした報告自体が、今後同じ探し方をする人のための誘導になるからです。また、重複する報告があまりに多発するようであれば、それはプロジェクトにとっては、問題の影響度合いの大きさのバロメーターにもなります。

重複として処理された報告を手がかりにして、適切な情報に辿り着ける

また、「この問題をこのプロジェクトに報告するのが適切かどうか分からない、もっと適したプロジェクトがあるかもしれない」という不安を感じたケースでも、思い切ってあなたが思った報告先にフィードバックすることを筆者はおすすめします。なぜなら、同じ一つの原因から起こる問題でも、報告する人によって問題に遭遇する経緯やきっかけは違うからです。

異なる経路から同じ原因にたどり着くこともある

代わりの適切な報告先に誘導されたり、開発者側でより適切な先へ報告がエスカレーションされたとしても、「自分の調べ方が甘かった」と凹む必要はありません。先の例同様、あなたの報告は、今後同様の経緯で問題に遭遇した人のための誘導になるからです。

まとめ

以上、「既知の問題や解決策がある事について報告しない(報告する前に、既存の報告や情報がないか探す)」という原則について、実例を挙げて解説してみました。

この解説は、OSSへのコントリビューションを増やすことを意図した取り組みであるOSS Gateで開催しているワークショップの中で得られた知見をまとめた本、「これでできる! はじめてのOSSフィードバックガイド」の一部を抜粋・再編集した物です。本編ではこのほかにも、問題の報告の仕方やありがちなミス、フィードバック初心者の方が戸惑いがちな点について、なるべく具体例を示しながら、幅広く解説してみています。リンク先では原稿の全文を公開していますが、手元に置いて参照しやすい形式での販売も行っていますので、読書スタイルに合った形式で参照して頂ければ幸いです。

OSS Gateでは、新型コロナウィルスの感染拡大防止の観点から、現在は東京地域を主体としたワークショップをオンライン(Discord)で開催しています。次回開催予定は12月12日(土曜)13:00からで、ビギナー(ワークショップで初めてのフィードバックを体験してみたい人)・サポーター(ビギナーにアドバイスする人)のどちらも参加者を募集中です。ご都合の付く方はぜひエントリーしてみて下さい。業務のチームのメンバーや後輩の方にOSSへのコントリビュートをしてもらいたいと思っている方は、自身をサポーターとして、メンバーや後輩の方をビギナーとして参加のお声がけをして頂くのもおすすめです。

また、当社では企業内での研修としてのOSS Gateワークショップの開催も承っています(例:アカツキさまでの事例)。会社としてOSSへの関わりを増やしていきたいとお考えの企業のご担当者さまは、お問い合わせフォームからご連絡頂けましたら幸いです。

  1. 矛盾する2つの指示を同時に与えられて身動きが取れなくなること。叱責の場面で黙って叱られていると「なんとか言ったらどうなんだ!」と言われ、抗弁すると「口答えするんじゃない!」と言われる、というような場面はその典型例。

  2. TwitterやFacebookなどのSNSでの投稿は、一般的なWebサイトを対象にした検索サービスでは見つけられないことがあり、そのサービス上で改めて検索する必要があります。

  3. 検索サービスによっては、これらに相当することをサービス側で自動的に行った上で結果を返す場合もあります。

  4. 筆者の場合、サポートサービスの運用規定によって、決まった工数の範囲内で必ず回答を返さなければいけないから、という前提もあります。