Previous: , Up: 大きなプログラムの保守   [Contents][Index]

29.7 バグリファレンス

ある程度のユーザーをもつプロジェクトのほとんどは、バグレポートを追跡するために一意で短い数値や識別子を割り当てる何らかの問題追跡ソフトウェアでバグレポートを追跡しています。これらはソースコード中でバグの修整コードのコメント、ドキュメントファイル、メーリングリストやIRCチャンネルでの議論において、与えられたバグにたいするリファレンスとして使用されます。

マイナーモードbug-reference-modeとbug-reference-prog-modeはそのようなバグリファレンスをハイライトして、対応するバグレポートをプロジェクトのissue trackerへフォローできるようにします。bug-reference-prog-modeは、ソースコードのコメントおよび文字列内部のバグリファレンスだけをハイライトするbug-reference-modeの変種です。

これが機能するためには、バグリファレンスの構文(bug-reference-bug-regexp)、およびバグレポートを照会できるトラッカーのURL(bug-reference-url-format)をBug Referenceモードが承知している必要があります。これらは通常はプロジェクト間で異なるので、ディレクトリーごとのローカル変数やファイル内のローカル変数で指定するのは理にかなっています。

たとえば自分たちのプロジェクトではバグレポートへのリファレンスを通常はbug#1234やBug-1234のように記述し、そのバグのissueトラッカーにおけるページがhttps://project.org/issues/1234なら、これらのローカル変数セクションは以下のようになります。 

;; Local Variables:
;; bug-reference-bug-regexp: "\\([Bb]ug[#-]\\([0-9]+\\)\\)"
;; bug-reference-url-format: "https://project.org/issues/%s"
;; End:

最初のregexpグループがキャプチャーした文字列は、オーバーレイbug-referenceの境界(ハイライトされてクリック可能になる部分)の作成を定義します。

bug-reference-bug-regexpの2つ目のregexpグループがキャプチャした文字列は、bug-reference-url-format内の%sテンプレートの置換に使用されます。

issueとマージリクエストが違うURLになるように、これらの区別にバグリファレンスの異なる部分を使用する必要がある等、より複雑なシナリオに対応するためにbug-reference-url-formatは関数でもよいことに注意してください。

自動セットアップ

bug-reference-modeがアクティブな場合には、bug-reference-mode-hookが実行して、bug-reference-bug-regexpとbug-reference-url-formatをどちらもセットせず、変数をセットできる関数が見つかるまでbug-reference-auto-setup-functions内の関数を呼び出して、これらの2つの変数への適切な値のセットアップを試みます。

セットアップ関数には、現在のところ3つのタイプがあります。

  1. 変数bug-reference-forge-alistおよびbug-reference-setup-from-vc-alistで設定できるバージョンコントロールされたファイルをセットアップする。デフォルトでは使用するissueトラッカーにhttps://debbugs.gnu.org、issueは通常はbug#13のように参照(ただし他の多くの表記も考慮)するGNUプロジェクト、そしてGitLab、Gitea、SourceHut、GitHubのような複数種類の現代的なソフトウェアフォージをセットアップできる(訳注: FOSS開発コミュニティーにおいてforgeとはコンピューターアプリケーションの開発および共有のためのウェブベースのグループウェアを意味する)。このようなフォージのインスタンスをセルフホスティングでデプロイしている場合には、bug-reference-forge-alistを通してそれをbug-referenceに伝えるのがもっとも簡単な方法である。
  2. メールフォルダーやmboxの名前から推察されるemail、および変数bug-reference-setup-from-mail-alistで設定できるメールヘッダー値をセットアップする。built-in、news-、およびメールヘッダーGnusによるEメールとUsenetニュースとRmailでメールを読むがサポートされている。
  3. 変数bug-reference-setup-from-irc-alistで設定できるIRCチャンネルをセットアップする。ビルトインのIRCクライアントであるRcirc (Rcirc in The Rcirc Manual)、およびERC (ERC in The ERC Manual)がサポートされている。

これらのモードのほとんどは、すべてbug-reference-modeを有効にするだけで充分ですが、Rmailだけは若干異なるセットアップが必要になります。 

;; バージョンコントロールされたファイルならVCベースのセットアップを使用
(add-hook 'prog-mode-hook #'bug-reference-prog-mode)

;; Gnus (summaryバッファーとarticleバッファー)
(add-hook 'gnus-mode-hook #'bug-reference-mode)

;; Rmail
(add-hook 'rmail-show-message-hook #'bug-reference-mode-force-auto-setup)

;; Rcirc
(add-hook 'rcirc-mode-hook #'bug-reference-mode)

;; ERC
(add-hook 'erc-mode-hook #'bug-reference-mode)

Rmailの場合には、モードフックのかわりに関数bug-reference-mode-force-auto-setup ( bug-reference-modeをアクティブにして強制的に自動セットアップを行う)と組み合わせてrmail-show-message-hookを使う必要があります。その理由はRmailではすべてのメッセージが同じバッファーにありますが、セットアップは別のメッセージが表示されるたびに実行される必要があるからです。

サードパーティ製パッケージへのサポートの追加

bug-referenceのauto-setupにたいするサポートの追加は、通常ならとても単純です。必要な情報(MUAの場合にはList-Id/To/From/Ccのメールヘッダー値)を集める引数なしのセットアップ関数を記述して、以下のヘルパー関数のいずれかを呼び出します:

セットアップ関数はbug-referenceモードをセットアップできるなら非nilをリターンします。これは上記のヘルパー関数のいずれかを呼び出すのが、関数が最後に行うこととなるケースです。

最後にそのセットアップ関数をbug-reference-auto-setup-functionsに追加する必要があります。

これらのauto-setup関数は最初のステップとして、major-modeをチェックする等によりそれらが適用可能かチェックする必要があることに注意してください。

デバッグパッケージとの統合

プロジェクトのissueがサーバーhttps://debbugs.gnu.orgでトラックされていれば、Packageメニュー(Emacs Lispパッケージを参照)でダウンロードできるdebbugsパッケージを使用して、Emacsから直接レポートの閲覧や回答ができます。このパッケージは、以下のようにbug-reference-modeとbug-reference-prog-modeの上にアクティブ化できるマイナーモードdebbugs-browse-modeを追加します: 

(add-hook 'bug-reference-mode-hook 'debbugs-browse-mode)
(add-hook 'bug-reference-prog-mode-hook 'debbugs-browse-mode)