bugz-mode -- Accessing bugzilla from Emacs
==========================================
bugz-mode provides an user interface to the bugzilla bug tracking
system. Underneath it uses the pybugz command-line program to
communicate with the remote server.
bugz-mode is designed to provide a simple but complete interface to
bugzilla: the goal is that you must be able to do all kind of
activities in the bug tracker without leaving Emacs, without X-window
and without a bloated modern web brower like firefox.
Requirements for running bugz-mode
----------------------------------
As already mentioned, bugz-mode depends on Pybugz, which is available
at http://www.github.com/williamh/pybugz.
You can either download and compile the python stuff or use a binary
package provided by your GNU/Linux distribution. `apt-get install
bugz' worked for me in my Debian system. The redhat package seems to
be named pybugz instead. No idea about other distros.
Installing bugz-mode
--------------------
If you are not using the new Emacs packaging system, just drop this
file in some directory in your load-path and do a require:
(add-to-list 'load-path "/path/to/dir/containing/bugz-mode")
(require 'bugz-mode)
Otherwise you can use M-xpackage-install-file for the elpa-like
installation.
Configuring bugz-mode
---------------------
The minimal configuration you need is to set a few variables telling
bugz-mode where is your bugzilla server and which credentials you will
be using for accessing it. Put something like the following in your
.emacs file:
(setq bugz-db-base "http://path.to.bugzilla.net/bugzilla/xmlrpc.cgi")
(setq bugz-db-user "mr.foo@bar.net")
Note that bugz-db-base expects the full path to the CGI script
implementing bugzilla's xmlrpc interface. This is probably always
under /bugzilla/xmlrpc.cgi, but who knows...
By default bugz-mode assumes that you will be storing your local cache
of bugs in ~/bugs. While it is a very reasonable default most likely
you will want to use some other location. Easy, add something like
this to your .emacs:
(setq bugz-db-dir "~/company/bugs")
Just make sure the directory exists! bugz-mode is lazy and wont
create it for you.
You will also probably want to associate the bugz-mode major mode to
edit files having the .bugz extension. So add it to your auto-mode
alist:
(add-to-list 'auto-mode-alist
(cons "\\.bugz$" 'bugz-mode))
And that is all! Well, actually there are several other not very
important things you can customize. Fire up M-xcustomize-group bugz
and take a look...
Getting started
---------------
The main entry point of bugz-mode is M-xbugz. Launch it!
If you did not do your homework and did not create a directory for
bugz-db-dir then M-xbugz will barf at you and fail. In that case
create the directory and try again.
Done? Good, run M-xbugz again and you will find yourself in the
so-called bugz summary buffer. This is the buffer where you do
searches and manage the resulting sets of bugs. By default the
summary buffer shows you the set of bugs which have been already
fetched from the bugzilla server and put in the local database in
bugz-db-dir. This fact is reflected by the [local] mark in the
buffer. Of course since this is the first time you run M-xbugz you
did not download any bug yet, so the list is empty. How boring :(
So, where are your bugs? Well, hopefully they are at the bugzilla
server whose url you configured in bugz-db-base. We have to fetch
them. For that purpose you must perform a search using some criteria.
If you push the key 's' while in the summary buffer you will be
presented with a "fast selection" buffer ala org-mode where you can
select the search criteria: bugs assigned to some specific hacker,
bugs having some severity, bugs containing `fuck' in some comment,
etc. Just select 'a' for getting the buffers assigned to you and
enter your username in the minibuffer. Then you will be back to the
fast selection buffer to add a new criteria. This way you can add any
number of search criterias to your search. End by pressing 'E' to
submit your search or by pressing ENTER in order to cancel the search.
For the moment just search for bugs assigned to you. If there are
bugs satisfying your criteria then bugz-mode will populate your
summary buffer with a list of lines describing them. Hurrah!
Note how the selection criteria used to fetch these bugs is
reflected in the [...] mark in the summary buffer. It must read
now something like [:assigned-to "my@email.com"]. Unless you used
the "local" search criteria, in which case it will read [local].
So, very nice, you have the list of bugs assigned to you in front of
you. You can navigate through them using the keys n, p and TAB. But
know what, the truth is that these bugs are not yet in your local
database! You fetched what could be considered some "headers"
describing which bugs satisfied your search criteria.
Now, there are several ways to get a bug fetched from the bugzilla
server. One is to simply select it. Go the entry of some of the bugs
(over the "bug XXXX" which looks like a link) and press ENTER.
After some seconds you will be drop in a buffer called XXXXX.bugz
where XXXXX is the id of the bug. Now this is much more interesting!
The buffer is in the Bugz major mode, and it is divided into two well
diferentiated parts.
The first part contains the headers of the bug: Title, Assigneee,
Reported, etc. What you see is actually a summary of the headers.
Push the key 't' in order to toggle the full view to see all the
headers.
The second part of the buffer contains whatever comments associated
with the bug. Each comment is preceded by a highlighted header of the
form [Comment #XX] blah.
Note how the bugzilla-like links ("bug xxx" and "attachment xxx") that
may be in the bug comments look like links. You can navigate through
the comment headers and the links using the TAB key.
But we will play with the links later. Now go back to the summary
buffer by either pressing 'h' or switching to the *Bugz* buffer. Note
that there is an asterisk at the beginning of the entry for the bug
that we just visited. This means that the bug is in the local
database. Visit the bug again... it must be instantaneous! Nothing
has to be fetched from the server.
Go back again to the summary buffer pressing 'h'. Select another bug
and press 'r'. This will fetch the bug from the bugzilla server
without visiting the bug. An asterisk mark must appear at the left of
this bug entry as well.
So if you are stil with me at this point you have a list of bugs in
the summary buffer. Some of them have been fetched (marked with an
asterisk) some others have been not. Now press 'l'. This shows you
the "local" bugs, i.e. the bugs stored in the local database. Those
are the bugs which are shown when you launch M-xbugz. You will see
that the [...] mark changes to [local] and that now the list only
contains the bugs which are in the local database.
Do another search and press 'R' in the summary buffer. This will
fetch all the bugs from the server, including the ones already
fetched! The reason for this is that it is possible for the bugs to
have changed in the bugzilla server. A new comment may have been
added, for example. Anytime, to make sure that your local database is
up to date with the bugzilla server, update your local bugs by
pressing 'l' and then 'R'. It is slow as hell but life sucks
sometimes.
Lets focus now on the bug buffers. Do some search and visit a bug
containing bugzilla links to other bugs and/or attachments. Then go
to some link and press ENTER. If it is a ling to a bug the bug will
be fetched and visited. If it is a link to an attachment the
attachment will be fetched and opened in an Emacs buffer. Once
fetched the attachments are stored in the bug-db-dir/attachments/
directory.
Pressing 'R' while in a bug buffer will re-fetch the bug from the
server and revert the buffer if needed. 'A' will fetch all links
present in the bug.
While visiting a bug, it is possible to visit the next bug in the
summary buffer by pressing 'n'. The same for the previous bug
pressing 'p'. This makes it easy to quickly navigate through the
result of some search.
Stored custom queries
---------------------
Having to introduce the same search criteria using 's', again and
again, can be a bit cumbersome and inconvenient. In order to
alleviate the pain you can define your own named queries in the
variable `bugz-custom-queries'. This is an example:
(setq bugz-custom-queries
'(("My bugs" ?m (:assigned-to user-mail-address :ordered-by "importance"))
("Blockers" ?b (:severity "blocker"))))
Here we are defining two queries, "My bugs" which refers to the
bugs assigned to me, and "Blockers" which refers to, well, nice
bugs blocking someone. The letter after the name will be used to
identify the query in a fast-selection buffer, so make it
meaningful.
The command to search for predefined queries is activated by pressing
'S' in both the summary buffer and bug buffers.
See the documentation of `bugz-custom-queries' for more information
about the keywords that you can use to define your search.
The unplugged mode
------------------
If you press 'J' in either the summary buffer or in some bug buffer
you will be toggling the bugz unplugged mode. When this minor mode is
activated then bugz-mode will never attempt to contact the bugzilla
server. Your actions will be limited in accordance! You will still
be able to access fetched buffers, but not a lot more.
So if you are going on a trip with no connectivity and foresee you
will be working in some bugs, search for them in the summary buffer
and fetch them all! I would also recommend doing 'A' in all of them
in order to fetch all their direct dependencies, attachments and what
not.
Changing bugs
-------------
You can add a comment to a bug by visiting its buffer and then
pressing 'C'. An input buffer will be opened where you must write
whatever you want to comment. Then press C-cC-c to submit the comment
to the server. After that you will be back in the bug buffer and you
will see it is updated with your new command in it.
The local database
------------------
bugz-mode maintains a small database of text files containing bugs and
attachments in whatever directory configured in bugz-db-base. This is
known as the "local database" and it is a sort of a cache between
bugz-mode and the remote bugzilla server. An example local database
looks like this:
~/bugs/14776.bugz
15522.bugz
15654.bugz
15724.bugz
attachments/2212
2100
The files having the .bugz extension are text files containing bug
descriptions as returned by pybugz. The files in the attachments/
directory contain... well, attachments.
Bugs for which there are a file in the local database are known to
be "local bugs". Note however that all the bugs in the local
database must also be present in the remote bugzilla: they were
fetched from it at some point.
Need more help
--------------
No, you don't. Explore, have fun, use C-hm, read the code...
Happy bug fixing!