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-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
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
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 Per-Directory Local Variables or see Local Variables in Files.
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
template in the
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.
bug-reference-mode is activated,
bug-reference-mode-hook has been run and still
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.
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-setup-from-mail-alist. The built-in news- and mailreader Email and Usenet News with Gnus and Reading Mail with Rmail are supported.
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
;; 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
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 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-vcwhich does the setup according to
bug-reference-maybe-setup-from-mailwhich does the setup according to
bug-reference-maybe-setup-from-ircwhich does the setup according to
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
Note that these auto-setup functions should check as a first step if
they are applicable, e.g., by checking the
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 Emacs Lisp Packages). This package adds
the minor mode
debbugs-browse-mode, which can be activated on
(add-hook 'bug-reference-mode-hook 'debbugs-browse-mode) (add-hook 'bug-reference-prog-mode-hook 'debbugs-browse-mode)