Previous: Emerge, Up: Maintaining [Contents][Index]
ある程度のユーザーをもつプロジェクトのほとんどは、バグレポートを追跡するために一意で短い数値や識別子を割り当てる何らかの問題追跡ソフトウェアでバグレポートを追跡しています。これらはソースコード中でバグの修整コードのコメント、ドキュメントファイル、メーリングリストや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モードが承知している必要があります。これらは通常はプロジェクト間で異なるので、Directory VariablesやFile Variablesで指定するのは理にかなっています。
たとえば自分たちのプロジェクトではバグレポートへのリファレンスを通常は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つのタイプがあります。
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に伝えるのがもっとも簡単な方法である。
bug-reference-setup-from-mail-alist
で設定できるメールヘッダー値をセットアップする。built-in、news-、およびメールヘッダーGnusと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メニュー(Packagesを参照)でダウンロードできる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)