この記事はOpenCV Advent Calendar 2023 2ndの25日目の記事です。
他の記事は目次にまとめられています。
■ TL;DR
なぜ、あなたはIssueを発行するのか？最後、どうしたいのか、を考えよう
- 「相談したい」ならば、Go to forum !
- 「解決したい」ならば、Make issue !
- issue作成は「ゴール」ではなく「スタート」、ここから一緒に伴走したい！
■ はじめに
OpenCVを使っていると、「あれ？この動作おかしいんじゃない？」ってことに直面する事が少なくないと思います。
ここでは、OpenCVでissueを発行するときに気を付けるべき事項をまとめておきます。
これを書いている人
- 興味もスキルも全くない部隊へ飛ばされ、開発からも外され、一年間を棒に振ったダメ人間
■ 悲しいissueがあるのです
OpenCV Issueを眺めていると、誰からも拾われない 可哀そうなIssue というのがポロポロと…。
- 誰もコメントをしない
- 誰もアサインされない
- 完全に黙殺されている
今回はこういう可哀そうなIssueが発行されないためには、どういう書き方をすればいいのか、をまとめてみる。
なお、このスキルは普段の「障害報告」などにも活用できるから、この記事は読んで損はない、はず！（と信じたい）
■ Step1) Issueにするべきか、Forum投稿にするべきか
その前に、まずIssueにするべきか、Forum投稿にするべきか、を考える必要がある。
OpenCV Forumはこちら。
Issue/Bug tracker
- ドキュメントにない振る舞いをした(Bug)
- プログラムが強制終了した！
- 想定していない結果が得られた！
- ドキュメントが間違っている(Document)
- パラメータの意味が違う
- ドキュメントにはない制約条件があった
- こんな機能を要望します (Feature Request)
Forum
- OpenCVの関数の使い方が分からない
■ Step2) Bug報告のIssueを作ろう
どうやら貴方はOpenCVのバグを踏み抜いたようだ。
貴方はもしかするとパッチを作れるのかもしれないし、誰かに直してもらう必要があるかもしれない。
それでは、どのようにしてIssueを作るべきか。
◯目的を考える
発行されるissueは大きく分けて２種類ある。
a. 貴方は困っている"感情"を、他人に共有したいのか？
b. 貴方が直面している問題を解決するために、他人に共有したいのか？
つまり、共感を主目的とするのか、問題解決を主目的とするのか、と言い換えてもいい。
もし誰かにその苦労を共感してもらいたいならば、issueを発行せずに、身近な人にお話ししてね💖
では、問題解決できるissueとなるためには、何が必要か？をまとめていく。
◯まず、最新版で確認する
2023/12現在、OpenCV Repositoryには大きく分けて3種類のtrunk/branchがある。
- 4.x : main trunk
- 5.x : 次世代バージョン
- 3.x : 更新予定無し
さて、例えば今、OpenCV 4.0を使っている貴方がバグを踏み抜いたとする。
商用ライブラリなどであれば、修正パッチが提供され、OpenCV 4.0.1 リリースなどという流れを期待できる。だが、基本的にそこまで手厚いフォローは期待しない/できない。次のリリースに含まれる。
- 4.x にバッチがインストールされる
- 5.x にパッチがマージされる（必要に応じて）
- 4.xから4.9 などのリリースバージョンがリリースされる
よって、問題に直面したら、まずは最新版で試す事が重要である。もしかするとすでに直っているのかもしれないし、直すとしても最新版にしかパッチが提供されない。
◯テンプレートに従う
New issueボタンを押下すると、こんな感じでテンプレート選択になる。
テンプレートには、バグ報告などにどのような情報が必要なのかがリストアップされているので、これに従って報告した方が記載するときも楽です。
◯重複する内容ではないことを確認する
issueを発行する前に、(a)FAQやForumで既に同じ質問がでていないか？ (b)同じ内容で既にissueが発行されていないか？、ということを確認する。
- FAQ
- 旧Forum
- 新Forum
- Issue
貴方が作成したissueは、その後他の人もsearchする可能性があります。よって、きちんと必要事項などが記載されていないと困ってしまいます。
◯英語で書く
- 日本語や中国語、韓国語など、英語以外でissueを発行しないでください
- 「いやいや、機械翻訳があるから、読めるでしょ？」という気持ちはわかります
- それならば、書き込む側が機械翻訳で書くこともできますよね
◯System Information
貴方が直面している問題を他人にも見てほしいならば、他人の環境でもその問題を再現できなければならない。そのための情報共有をお願いします。
System Information
Please provide the following system information to help us diagnose the bug. For example:
// example for c++ user
OpenCV version: 4.8.0
Operating System / Platform: Ubuntu 20.04
Compiler & compiler version: GCC 9.3.0
// example for python user
OpenCV python version: 4.8.0.74
Operating System / Platform: Ubuntu 20.04
Python version: 3.9.6
GCCやClangなどのコンパイラでメジャーバージョンが変わると、デフォルトの振る舞いが大きく変わる事もある。また、同じOSでも異なるコンパイラを使う事も可能。なので、ここはしっかり記載してほしい。
例えば、Raspiを使っている場合には、Operating System / Platform: Ubuntu 20.04(rasberry pi 4) などと補足をした方が明確になる。
◯Detailed Description
ここは、具体的にどんな問題が起きているのか、それがどのような問題なのか、を記載する（再現手順については次欄に記載するので、ここでは書いてもあっさりでよい）。
例）
- この関数にこの引数を渡すと、例外が発生してプログラムが落ちる
- この関数にこの引数を渡すと、ドキュメントから読み取れる結果と違う
◯Steps to reproduce
再現ステップを記載する。もしコードが長すぎる場合、https://gist.github.com/ の活用も考慮して下さい。
サンプルコードについては、 stack overflowの再現可能な短いサンプルコードの書き方にまとまっている。はっきり断言しよう、issueを発行する人間は 「必読」 である。
質問をする際、第三者が質問の内容を理解し、手元で問題を再現できるような良いサンプルコードを含めると、より良い回答をもらいやすくなります。この「良いサンプルコード」を作るための条件がいくつかあります：
- 短くテキストで：できるだけコードを削った上で、同じ問題が出るようにする。
- 自己完結している：問題を再現するために必要なコードとデータを漏れなく書く。
- 再現可能である：投稿する前にサンプルコードを実行してみて、問題が再現するかどうかを確認する。
このページでは、どうやって「良いサンプルコード」を作るかの方法を説明します。
もう１つ重要なのは、「再現に必要なデータが添付されている事」である。もし再現データを共有できないならば、同じ問題を再現できる別データを用意するか、あるいは、あきらめて自分のところでローカルに直すか、しかない。
コード等を張り付ける時は、``` ～ ```で囲むコードブロック記法を使いましょう。
ベタ張りされてしかも表示が崩れているissueは、その時点で見るのを止めるくらい悪印象です。
cmakeオプションとbuild info
特にbuild関係での問題の場合は、CMakeを実行したときの、コマンド引数とbuild informationがあると調査がやりやすくなりますね…
単純な作業ミスから、自分がやっているつもりの行動と、実際の行動は一致しない、という事が度々あります。ログベースで報告をお願いします。例えば、スペルミスするかもしれないです、人間ですから…
cmake -S opencv -B build4-main -DENABEL_NEON=ON
◯Issue submission checklist
最後に確認事項がいくつかある。とはいえこれらは既に上記で全部確認済みだろう。
- I report the issue, it's not a question *
- I checked the problem with documentation, FAQ, open issues, forum.opencv.org, Stack Overflow, etc and have not found any solution
- I updated to the latest OpenCV version and the issue is still there
- There is reproducer code and related data files (videos, images, onnx, etc)
■ Step 3) Issueを作ったその後は
さて、issueを作る事は「ゴール」ではなく、「スタート」である。ここから全てが始まる。
- 興味を抱いてくれた人が、コメントを残してくれるかもしれない。
- 「これ、こういうこと？」「この内容もうちょっと詳しく教えて」とか追加質問がでる。
- 「パッチ書いたぜー、これで確認してみてくれー」とパッチが出てくるかもしれない。
大切なのは、バグ報告者も一緒に問題解決する事である。
◯Closing
さて、問題を無事に解決出来たら、きちんとissueをclosingしよう。なお、修正パッチ(pull request)を作成するときに、issueと紐づけることもできる。これで修正パッチが取り込まれると自動的に当該issueもクロージングになる。
■ 最後に
OSS開発に協力する人間の中には（私のように）職業としてではなく、趣味で協力している人も少なからずいます。
協力者にとっては「面白そうな課題」「需要そうな課題」かつ「自分にも取り組めそうな課題」であるかどうかが、issueに着手するかどうかのスタートラインになります。
問題解決を目的とするならば、issue発行は「ゴール」ではなく、「スタート」ラインです。そこから一緒に協力者はゴール目指して伴走したいのです。よろしくお願いします！！
■ 補足（結びの挨拶）
今年も一年、お世話になりました。（私信）全く興味ない技術分野へ飛ばされ、強制的に転居（しかも自腹）、コロナ、社内ニート化するなど、激動の１年でした。本当にもう疲れました。来年はもう少し実りある一年にしたいです。皆様にとっては、良い年末・クリスマス・お正月を過ごされることを心よりお祈り申し上げます。