一定規模のユーザーを抱えるほとんどのプロジェクトでは、各バグレポートに一意で短い番号や識別子を割り当てる何らかの課題管理ソフトウェアを用いてバグレポートを追跡しています。これらは、例えばバグを修正するコードの上にあるソースコードのコメントや、ドキュメントファイル、あるいはメーリングリストやIRCチャンネルでの議論などで、特定のバグを参照する際に使用されます。
マイナーモード bug-reference-mode と bug-reference-prog-mode
は、こうしたバグ参照をハイライトし、プロジェクトのイシュートラッカーにある対応するバグレポートまで辿れるようにします。bug-reference-prog-mode は bug-reference-mode
の派生版で、ソースコードのコメントや文字列内のバグ参照のみをハイライトします。
動作にあたり、バグ参照モードではバグ参照の構文（bug-reference-bug-regexp）と、バグレポートを検索できるトラッカーのURL（bug-reference-url-format）を把握しておく必要があります。これらは通常プロジェクトごとに異なるため、ディレクトリごとのローカル変数またはファイル内のローカル変数を参照して指定するのが適切です。
例えば、本プロジェクトでは通常、バグレポートへの参照を bug#1234 や Bug-1234 のように記述し、イシュートラッカー上のこのバグのページが 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:
最初の正規表現グループで捕捉された文字列は、overlay bug-reference が生成する範囲、すなわちハイライトされてクリック可能になる部分を定義します。
bug-reference-bug-regexp の 2
番目の正規表現グループでキャプチャされた文字列は、bug-reference-url-format
内の %s テンプレートを置換するために使用されます。
なお、bug-reference-url-format
は、より複雑なシナリオに対応するための関数である場合もあります。例えば、バグ参照の異なる箇所を用いてイシューとマージリクエストを区別する必要があり、その結果、異なる
URL が生成される場合などが挙げられます。
bug-reference-mode が有効化され、bug-reference-mode-hook が実行済みで、かつ bug-reference-bug-regexp または bug-reference-url-format のいずれかが依然として nil である場合、モードは bug-reference-auto-setup-functions
内の関数を一つずつ呼び出し、いずれかが成功するまで繰り返すことで、これら2つの変数に適した値を自動的に見つけ出そうとします。
現在、セットアップ関数は3種類あります。
bug-reference-forge-alist および bug-reference-setup-from-vc-alist
で設定可能な、バージョン管理対象ファイルの設定です。デフォルト設定では、https://debbugs.gnu.org
をイシュートラッカーとして使用し、イシューを通常 bug#13 として参照する GNU
プロジェクト（ただし、他にも多くの異なる表記法が考慮されています）のほか、GitLab、Gitea、SourceHut、GitHub
といった数種類のソフトウェアフォージを設定できます。このようなフォージのセルフホストインスタンスをデプロイする場合、バグ参照について伝える最も簡単な方法は
bug-reference-forge-alist を利用することです。
bug-reference-setup-from-mail-alist
で設定可能なメールヘッダー値に基づくメール推測機能。組み込みのニュース・メールリーダーである GnusによるメールおよびUsenetニュース と Rmailによるメール閲覧 がサポートされています。
bug-reference-setup-from-irc-alist で設定可能な IRC
チャンネルの設定。組み込みの IRC クライアントである Rcirc（The Rcirc
Manual の Rcirc
を参照）および ERC（The ERC Manual の ERC
を参照）がサポートされています。
これらのモードのほぼすべてにおいて、単に bug-reference-mode
を有効にするだけで十分です。Rmail だけは、わずかに異なる設定が必要です。
;; Use VC-based setup if file is under version control. (add-hook 'prog-mode-hook #'bug-reference-prog-mode) ;; Gnus (summary & article buffers) (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を有効化して自動セットアップを強制する関数bug-reference-mode-force-auto-setupと組み合わせてrmail-show-message-hookを使用する必要があります。その理由は、Rmailではすべてのメッセージが同一のバッファに格納されるものの、別のメッセージが表示されるたびにセットアップを行う必要があるためです。
バグ参照の自動セットアップ機能の追加は、通常非常に簡単です。必要な情報を収集する引数なしのセットアップ関数（例：MUAの場合はList-Id/To/From/Ccといったメールヘッダーの値）を記述し、その後、以下のヘルパー関数のいずれかを呼び出すだけです：
bug-reference-maybe-setup-from-vc（bug-reference-setup-from-vc-alistに従ってセットアップを行う）；
bug-reference-maybe-setup-from-mail（bug-reference-setup-from-mail-alistに従ってセットアップを行う）、および
bug-reference-maybe-setup-from-ircで、bug-reference-setup-from-irc-alistに従ってセットアップを行います。
セットアップ関数は、バグ参照モードを設定できた場合には nil
以外の値を返すべきです。これは、関数の最後の処理が上記のヘルパー関数のいずれかを呼び出す場合に当てはまります。
最後に、セットアップ関数をbug-reference-auto-setup-functionsに追加する必要があります。
なお、これらの自動セットアップ関数では、まずmajor-modeの値を確認するなどして、適用可能かどうかを判定する必要があります。
プロジェクトのイシューがサーバー https://debbugs.gnu.org
で追跡されている場合、パッケージメニュー（Emacs Lisp
パッケージ を参照）からダウンロードできる debbugs パッケージを使用して、Emacs
上で直接レポートを閲覧したり返信したりできます。このパッケージはマイナーモード debbugs-browse-mode を追加し、bug-reference-mode や bug-reference-prog-mode の上に次のように有効化できます：
(add-hook 'bug-reference-mode-hook 'debbugs-browse-mode) (add-hook 'bug-reference-prog-mode-hook 'debbugs-browse-mode)