28.7 Bug Reference

Most projects with a certain amount of users track bug reports in some issue tracking software which assigns each report a unique and short number or identifier. Those are used to reference a given bug, e.g., in a source code comment above the code fixing some bug, in documentation files, or in discussions on some mailinglist or IRC channel.

The minor modes bug-reference-mode and bug-reference-prog-mode highlight such bug references and make it possible to follow them to the corresponding bug report on the project’s issue tracker. bug-reference-prog-mode is a variant of bug-reference-mode which highlights bug references only inside source code comments and strings.

For its working, bug reference mode needs to know the syntax of bug references (bug-reference-bug-regexp), and the URL of the tracker where bug reports can be looked up (bug-reference-url-format). Since those are typically different from project to project, it makes sense to specify them in see Directory Variables or see File Variables.

For example, let’s assume in our project, we usually write references to bug reports as bug#1234, or Bug-1234 and that this bug’s page on the issue tracker is https://project.org/issues/1234, then these local variables section would do.

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

The string captured by the first regexp group defines the bounds of the overlay bug-reference creates, i.e., the part which is highlighted and made clickable.

The string captured by the second regexp group in bug-reference-bug-regexp is used to replace the %s template in the bug-reference-url-format.

Note that bug-reference-url-format may also be a function in order to cater for more complex scenarios, e.g., when different parts of the bug reference have to be used to distinguish between issues and merge requests resulting in different URLs.

Automatic Setup

If bug-reference-mode is activated, bug-reference-mode-hook has been run and still bug-reference-bug-regexp, and bug-reference-url-format aren’t both set, it’ll try to setup suitable values for these two variables itself by calling the functions in bug-reference-auto-setup-functions one after the other until one is able to set the variables.

Right now, there are three types of setup functions.

1. Setup for version-controlled files configurable by the variables bug-reference-forge-alist, and bug-reference-setup-from-vc-alist. The defaults are able to setup GNU projects where https://debbugs.gnu.org is used as issue tracker and issues are usually referenced as bug#13 (but many different notations are considered, too), and several kinds of modern software forges such as GitLab, Gitea, SourceHut, or GitHub. If you deploy a self-hosted instance of such a forge, the easiest way to tell bug-reference about it is through bug-reference-forge-alist.
2. Setup for email guessing from mail folder/mbox names, and mail header values configurable by the variable bug-reference-setup-from-mail-alist. The built-in news- and mailreader Gnus and Rmail are supported.
3. Setup for IRC channels configurable by the variable bug-reference-setup-from-irc-alist. The built-in IRC clients Rcirc, See Rcirc in The Rcirc Manual, and ERC, See ERC in The ERC Manual, are supported.

For almost all of those modes, it’s enough to simply enable bug-reference-mode, only Rmail requires a slightly different setup.

;; 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)

In the Rmail case, instead of the mode hook, the rmail-show-message-hook has to be used in combination with the function bug-reference-mode-force-auto-setup which activates bug-reference-mode and forces auto-setup. The reason is that with Rmail all messages reside in the same buffer but the setup needs to be performed whenever another messages is displayed.

Adding support for third-party packages

Adding support for bug-reference’ auto-setup is usually quite straight-forward: write a setup function of zero arguments which gathers the required information (e.g., List-Id/To/From/Cc mail header values in the case of a MUA), and then calls one of the following helper functions:

• bug-reference-maybe-setup-from-vc which does the setup according to bug-reference-setup-from-vc-alist,
• bug-reference-maybe-setup-from-mail which does the setup according to bug-reference-setup-from-mail-alist,
• and bug-reference-maybe-setup-from-irc which does the setup according to bug-reference-setup-from-irc-alist.

A setup function should return non-nil if it could setup bug-reference mode which is the case if the last thing the function does is calling one of the helper functions above.

Finally, the setup function has to be added to bug-reference-auto-setup-functions.

Note that these auto-setup functions should check as a first step if they are applicable, e.g., by checking the major-mode value.

Integration with the debbugs package

If your project’s issues are tracked on the server https://debbugs.gnu.org, you can browse and reply to reports directly in Emacs using the debbugs package, which can be downloaded via the Package Menu (see Packages). This package adds the minor mode debbugs-browse-mode, which can be activated on top of bug-reference-mode and bug-reference-prog-mode as follows:

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