ある程度のユーザーをもつプロジェクトのほとんどは、バグレポートを追跡するために一意で短い数値や識別子を割り当てる何らかの問題追跡ソフトウェアでバグレポートを追跡しています。これらはソースコード中でバグの修整コードのコメント、ドキュメントファイル、メーリングリストや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はどちらも依然としてnilのままです。このモードはbug-reference-auto-setup-functionsの中のいずれかの関数が成功するまで順次呼び出すことによって、これら2つの変数にたいする適切な値を自動的に見つけようと試みます。
セットアップ関数には、現在のところ3つのタイプがあります。
bug-reference-forge-alistおよびbug-reference-setup-from-vc-alistで設定できるバージョンコントロールされたファイルをセットアップする。デフォルトではissueを通常はbug#13のように参照(ただし他の多くの表記も考慮)するGNUプロジェクト(issueトラッカーとしてhttps://debbugs.gnu.orgを使用)、そしてGitLab、Gitea、SourceHut、GitHubのような複数種類のソフトウェアフォージをセットアップできる(訳注:
FOSS開発コミュニティーにおいてforgeとはコンピューターアプリケーションの開発および共有のためのウェブベースのグループウェアを意味する)。このようなフォージのインスタンスをセルフホスティングでデプロイしている場合には、bug-reference-forge-alistを通してそれをbug-referenceに伝えるのがもっとも簡単な方法である。
bug-reference-setup-from-mail-alistで設定できるメールヘッダー値をセットアップする。built-in、news-、およびメールヘッダーGnusによるEメールとUsenetニュースとRmailでメールを読むがサポートされている。
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-setup-from-vc-alistに応じたセットアップを行うbug-reference-maybe-setup-from-vc
bug-reference-setup-from-mail-alistに応じたセットアップを行うbug-reference-maybe-setup-from-mail
bug-reference-setup-from-irc-alistに応じたセットアップを行うbug-reference-maybe-setup-from-irc
セットアップ関数は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)