@section Bug Reference
@cindex 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
+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.
@findex bug-reference-mode
@findex bug-reference-prog-mode
-The minor modes @code{bug-reference-mode} and
+ The minor modes @code{bug-reference-mode} and
@code{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. @code{bug-reference-prog-mode} is a variant
@vindex bug-reference-bug-regexp
@vindex bug-reference-url-format
-For its working, bug reference mode needs to know the syntax of bug
+ For its working, bug reference mode needs to know the syntax of bug
references (@code{bug-reference-bug-regexp}), and the URL of the
tracker where bug reports can be looked up
(@code{bug-reference-url-format}). Since those are typically
merge requests where each of them has a different URL.
+@heading Automatic Setup
+
+@vindex bug-reference-auto-setup-functions
+If @code{bug-reference-mode} is activated,
+@code{bug-reference-mode-hook} has been run and still
+@code{bug-reference-bug-regexp}, and @code{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
+@code{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.
+
+@enumerate
+@item
+Setup for version-controlled files configurable by the variable
+@code{bug-reference-setup-from-vc-alist}. The default is able to
+setup GNU projects where @url{https://debbugs.gnu.org} is used as
+issue tracker, Github projects where both bugs and pull requests are
+referenced using the @code{#42} notation, and GitLab projects where
+bugs are references with @code{#17}, too, but merge requests use the
+@code{!18} notation.
+
+@item
+Setup for email guessing from mail folder/mbox names, and mail header
+values configurable by the variable
+@code{bug-reference-setup-from-mail-alist}. The built-in news- and
+mailreader @ref{Gnus} and @ref{Rmail} are supported.
+
+@item
+Setup for IRC channels configurable by the variable
+@code{bug-reference-setup-from-irc-alist}. The built-in IRC clients
+Rcirc, @xref{,,,Rcirc, Rcirc}, and ERC, @xref{,,,ERC, ERC}, are
+supported.
+@end enumerate
+
+For almost all of those modes, it's enough to simply enable
+@code{bug-reference-mode}, only Rmail requires a slightly different
+setup.
+
+@smallexample
+;; 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)
+@end smallexample
+
+In the Rmail case, instead of the mode hook, the
+@code{rmail-show-message-hook} has to be used in combination with the
+function @code{bug-reference-mode-force-auto-setup} which activates
+@code{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.
+
+
@heading Integration with the debbugs package
@findex debbugs-browse-mode