Vimの問題を見つけた時の報告のしかた

  • Author: MURAOKA Taro
  • Date: 2011/12/28

Vimを利用していてなんかおかしいなって思った時にどうしてますか?是非、問題として報告してください。今回は日本語で報告する方法をご紹介いたします。

Vimを利用していてなんかおかしいなって思った時にどうしてますか?理想を言えば英語でvim-devへ報告できることですが、ちょっと日本人には敷居が高いですよね。そんな時は是非vim-jpまで不具合として報告してください。今回は日本語で報告する方法をちょっと細かく紹介いたします。

問題発見から報告までの流れ

まずは実例ということで、ちょうど今さっき私が発見した問題を報告するまでのストーリーを紹介します。

  1. Vimを使う 「Vim Advent Calendarの欠番を埋めるため、正規表現を使ったネタスクリプトでも書くかー」 :help pattern.txt 「なんか使ったこと無い正規表現の機能はないかなー 行をまたいだ操作したいなー」 /line<CR>

  2. あれなんか動作がおかしいな 「ありゃ? 検索のハイライトと、カーソル位置がズレるぞ?」 nnnnn...V 「あ。なんかでてきた。concealか」

  3. とりあえず報告だ 「明らかにバグだね。 なんで誰も指摘してないんだ?いや指摘されてるかもだけど、報告しとけ」 https://github.com/vim-jp/issues/issues/115

報告場所の選択

Vimの問題を報告する上で良いとされる方法は2つあります。

  • githubのvim-jp/issues
  • Googleグループのvim_jp

どちらでも好きな方を使ってください。前者はgithubのアカウントが、後者はGoogleアカウントが必要ですが、どちらも取得は簡単&無料です。既にアカウントがあるならgithubのほうが気軽でよいでしょう。Googleグループはメーリングリストも兼ねてますので、メールだけで利用できます。非開発者の人はGoogleグループのほうが気軽かもしれません。

報告のコツ

あなたが発見した問題をあなた自身が直すつもりでないのなら、それが修正される可能性を高めるために報告の際に気をつけたほうが良いこと、いわば報告のコツがいくつかあります。そのコツの代表的なものを紹介しておきます。

  • わかりやすいタイトルを書く 短く簡潔に、でも問題の内容がなるべくわかるように書くのが良いです。せっかくの報告も読む人の目に、それを直せる人の目に止まらなければ意味がありません。彼らも機械ではなく、また多くの報告を見ているわけですから、ちょっとタイトルだけみて「ややこしそうだな」とか「何言ってんのかわかんねぇな」と思う報告については、どうしたって後回しにしてしまいます。ですから短く簡潔に書いて「お、ちょっとちゃんと見てみようか」と思わせることは、早く直してもらう上で実はとっても重要です。

  • 再現方法/手順を書く 問題を発見するにあたり、または再現するのにあたり、どのような操作をしたのか可能な限り順を追って書いてください。vim-jpでは見ていませんが、世の中のオープンソースプロジェクトでは、まれにいかに自分が困ってるかだけを書くことに終始してしまい、どうやってその問題を発生させるのかを一切書かない人がいます。それでは問題は修正されず、報告に費やしたエネルギーはただの無駄になってしまいます。

  • (オプション)再現した環境を書く 同じVimといっても設定や環境は人それぞれです。特にVimは多くのプラットフォームをサポートし、多くのプラグインが存在していますので、それらの違い一つ、組み合わせ一つで問題が発生したりしなかったりします。これらを書くことは非常に重要です。慣れてくれば必要な分だけ報告することができるようになります。慣れない場合にはVimで :source $VIMRUNTIME/bugreport.vim を実行して、作成された bugreport.txt ファイルを報告に添付すると良いでしょう。

  • 期待する動作を示す 自分が、Vimはどのように振る舞うべきだと思っているかを書いてください。場合によってはそれが誤っている可能性もゼロではありません。しかしそれが間違っていることは悪いことではありません。むしろそのように誤解いしやすいことがわかり、今後の対策が検討できるので非常に良いことです。なので「もしかしたら自分が間違ってるかも」なんていう気持ちは一切忘れて、どう動いて欲しいと考えているかを書いてください。

  • 実際の動作を示す 実際にはどうなったかを書いてください。これを書かないと報告の意味はまったくありませんから、絶対に忘れたり省略したりしないでください。また「期待する動作」と明確に分けてください。期待と観測(実際)が入り交じっていると、その切り分けだけで直す人たちはゲンナリしてしまいます。

  • (オプション)推測される原因を書く あなたが十分にVimに詳しければ、おおよその原因の推測ができるようになってきます。その時は是非書いてみてください。当たっていれば大幅な時間の短縮になるのに加えて「なんか嬉しい」ですし、外していたとしても関係者がVimへの造詣を深めるキッカケとなります。

もちろんこれらは無視することもできますが、せっかく報告するのですから少しでも修正される可能性は高くしておいて損はないでしょう。

その他、知っておいてほしいこと

その他、問題報告の際に知っておいてほしいことを、vim-jpでの流儀と、一般的な流儀とを分けて紹介しておきます。

vim-jpでの問題報告の際に

まず少しでも問題だと思ったことは遠慮せずに報告をしてください。一般的なオープンソースプロジェクトでは「あらかじめ重複した報告が無いか調べて」と言っていたり、その他の条件をつける場合もあるでしょう。しかしvim-jpでは報告の心理的バリアを少しでも下げることを重要視しています。そのため「あれ?なんかおかしいな」と思ったら、まずは報告することを選択肢に入れてください。

また各種プラグインへの報告もwelcomeです。もちろんプラグイン作者へ直接連絡をとっていただくのがいろんな意味でベストではあるのですが、作者が外国の方である場合や直接の連絡を取るという行為が、シャイな日本人にとって敷居が高いのは認めざるを得ません。そんな時はvim-jpへ報告してください。その報告に賛同するvim-jpの参加者が転送したりしますし、作者自身がvim-jpの参加者である場合も少なくないでしょう。

一般的な問題報告の際に

報告の際には「バグ」という言葉はなるべく避けてあげてください。そうでなくてもプログラマーという人種は日々「バグ」に怯えています。そんな中で「バグがあるからなんとかして」と言われると必要以上に身構えてしまいます。英語圏ではbugという言葉ではなく、issueという言葉を使うことが増えています。日本語では「バグ」に代えて、「問題」とか「課題」とか、そういう言葉を選んであげるのが人としての優しさ・度量を示すことになり、ひいては問題を解決するまでの時間を短くすることにつながります。


以上、本記事は当初Vim Advent Calendarの28日目(笑)の代打記事用として急遽書かれました。

2011/12/28 22:00追記

が thinca さんがもっとふさわしい記事を書いてくれたので、こちらはエントリーから外しましたw