- Known issues and limitations
- Installation
- Supported backends
- Modes
- Interactive functions
- Customization
- org-mode integration
- Proxy use
- Rich text formatting
- Related modes and modules
To get an overview of open issues, report bugs, or suggest improvements please visit the GitHub issue tracker.
To report a bug, please first try if you can reproduce it. If you can, temporarily enable debug output for both bug-mode ((setq bug-debug t)) and url ((setq url-debug t)), reproduce the issue again, and include the contents of the *bug-debug* and *URL-DEBUG* buffers with your bug report. Make sure to replace the contents of Authorization and zsessionid headers before submission. Also include backtraces, if any.
If you’re interested in contributing please have a look at the developer documentation.
- json.el, which nowadays should be included in your copy of emacs already.
For historical reasons the API used for Bugzilla is the JSON-RPC API, which has been deprecated. Currently this is used as default API if no bug tracker type has been configured. In the future it is expected to keep the JSON-RPC API for backwards compatibility with older instances, but implement the REST WebService API as additional backend for newer Bugzilla instances.
A Bugzilla instance >= 3.6 with JSON-RPC enabled is required.
For Rally REST/JSON based Web Services API in version 2 is implemented (the latest version at the moment of writing this manual).
bug-mode is used to display details for a single bug, either from a search result or by searching/opening a single bug.
- RET - open attachment with browse-url function
- b - open bug in default browser
- c - add comment (deprecated, will be removed)
- d - download attachment with w3m-download
- e - edit the field near point, if editable
- i - display information about thing at point (debug functionality)
- r - remember the bug in a locally stored list
- s - resolve the bug (deprecated, will be removed)
- u - execute query again and update bug buffer
- q - kill bug buffer
- C-c C-c - Commit changes made to the bug tracker
The keybindings marked as deprecated rely on Bugzilla specific behaviour, and will be removed or change behaviour once backend agnostic support for those features is available.
bug-list-mode is used to display a list of bugs, usually as a result of a search. Full bugs can be opened in bug-mode either from the keyboard by navigating to an entry and pressing RET, or by mouse using either the left or the middle button.
- RET - open bug at point
- i - display information about thing at point (debug functionality)
- u - execute query again and update search buffer
- q - kill search buffer
Use the bug-rally-subscription function to display details about your Rally subscription.
Clear cached data, either globally, or – when called with prefix argument – for a particular instance.
Explicitely log in to a Bugzilla instance.
Explicitely log out from a Bugzilla instance.
Open a single bug, taking the internal bug ID as argument. For Bugzilla the internal and user visible bug ID are identical, while for Rally the user friendly ID (like “US123”) and the internal bug ID don’t match.For bug trackers like Rally you can use bug-search with a bug reference as argument, which will resolve the internal ID, and open it via bug-open, at the cost of one additional API call.
Entry point to bug-rally-subscription-mode
Search for bugs, and display them in bug-list-mode. The exact behavior depends on the bug tracker used.
Bugzilla supports
- free form text query
- key-value (e.g. “component:Test”)
- the name of a named search
Rally supports
- free form text query
- complex query in Rally query syntax
Both Bugzilla and Rally directly open a bug view instead of a list if the search term matches a bug identifier, or the search only returned a single result.
Search for bugs with multiple criteria. Same query format as bug-search.
Open a list of locally stored bugs.
As enduser it’s recommended to configure bug-mode using Emacs “Easy Customization Interface”, invoked with M-x customize-group RET bug:
The easiest way to change the faces used in bug mode is via M-x customize-group RET bug-faces:
To enable basic org-mode integration do a (require 'org-bug) after initializing bug-mode. This will provide two hyperlink types for use in org-mode. The format for both types is <bug tracker instance>/<bug identifier>. The instance identifier may not be omitted.
The bug link type provides a link to a single bug, requiring a unique identifier. For Rally a link could look like this: bug::test-rally/adff50be-40ec-4739-8615-d77ac5429bac.
The bug-search link type provides a link to a bug search. For Rally this can be used to easily link to a user friendly bug name, like this: bug::test-rally/US2. A simple text search could be done like this: bug-search::test-rally/may get eaten.
The org-mode integration supports org-capture from bug-mode and bug-list-mode (search result) buffers. Calling =org-capture anywhere in a bug-mode buffer will capture a link to the bug. Calling org-capture in a bug-list-mode buffer will capture a link to the bug at point.
HTTPS proxy support in emacs has been broken for quite a while, for details read bug 11788. As a result, doing something like the following will at best lead to interesting results if your bug tracker is only reachable via https for authenticated operations (which it should be):
(setq url-proy-services
'(("no_proxy" . "^\\((localhost\\|10.*\\)")
("http" . "a.proxy.example")
("https" . "a.proxy.example")))There are multiple possible workarounds, some of them are documented here in order of desirability.
A patched version of url is included for emacs 24.5. You can start using
it by setting bug-patched-url to t. The changes should not interfere
with other packages (apart from fixing https proxy use for them as well),
and if no patched version was found matching your emacs it just falls back
to the default url package – setting this option should have no negative
impact.
If you’re using emacs 25 you can just grab the patch from git
(2d1a6054b161bd1055d4feb11c8c5ac95543f5db) and apply it.
If your proxy allows using CONNECT, and you have a suitable shell host
available you can use this to forward a local port to Rally, bypassing the
whole proxy mess. An example entry for ~/.ssh/config could look like this:
Host rally-forward
ProxyCommand /usr/bin/connect-proxy -H a.proxy.example:8080 a.shellhost.example 443
LocalForward 9900 rally1.rallydev.com:443
Additionally /etc/hosts needs rally1.rallydev.com added after 127.0.0.1
to have it resolve to localhost, and the URL bug-mode uses to access Rally needs
to be adjusted to include the locally bound port:
(setq bug-rally-url "https://rally1.rallydev.com:9900/slm/webservice/v2.0/")After starting a SSH connection (ssh rally-forward) you should be able to use
bug-mode without issues.
OpenSSL’s s_client gained proxy support in trunk. Assuming your network allows host resolution it might be possible to use this as workaround:
;; disable builtin gnutls
(if (fboundp 'gnutls-available-p)
(fmakunbound 'gnutls-available-p))
;; set openssl compiled from trunk as tls-program
(setf tls-program
'("openssl-trunk s_client -connect %h:%p -proxy a.proxy.example:8080 -ign_eof"))Note that this will bypass the whole noproxy logic, so if you’re using tls in the local network without proxy as well this will break things.
Rally supports “Rich Text” (they mean “HTML”) for some fields. While for most of the options the value is questionable, and looks more like “Look! We can do fancy text too!”, the list formatting and the option to emphasize text using bold/italics/underline are quite useful. Even though a few more formatting options are supported you should limit yourself to those.
A rendering of a bug using all of Rallys Rich Text elements looks like this:
rally-mode queries all tasks for the user in the current iteration, and allows displaying details. This only works if tasks are added to an iteration, not user stories.
A very similar result can be obtained with bug-mode with the following code:
(bug--do-rally-search
'((resource . "Task")
(list-columns . ("FormattedID" "Name" "State" "Estimate" "ToDo"))
(data .
((fetch "true,WorkProduct,Tasks,Iteration,Estimate,State,ToDo,Name,Description,Type,FormattedID")
(query "(( Owner.Name = <your_user> ) AND (( Iteration.StartDate <= today ) AND ( Iteration.EndDate >= today )))"))))
:<rally-instance>)To query for user stories instead of tasks replace the Task with HierarchicalRequirement
A mode for using Bugzilla, wrapping the pybugz utility. Of limited use, as pybugz is rather picky about which Bugzilla instances it likes to work with.
A library wrapping most of GitHubs API. For adding GitHub issues to bug-mode just directly querying the GitHub API might be easier.
A library for using Jiras REST API.