Bugs Everywhere (BE) is a bugtracker built on distributed revision control. The idea is to package the bug information with the source code, so that developers working on the code can make appropriate changes to the bug repository as they go. For example, by marking a bug as “fixed” and applying the fixing changes in the same commit. This makes it easy to see what’s been going on in a particular branch and helps keep the bug repository in sync with the code.
However, there are some differences compared to centralized bugtrackers. Because bugs and comments can be created by several users in parallel, they have globally unique IDs rather than numbers. There is also a developer-friendly command-line interface to compliment the user-friendly web and email interfaces. This tutorial will focus on the command-line interface as the most powerful, and leave the web and email interfaces to other documents.
If your distribution packages BE, it will be easiest to use their package. For example, most Debian-based distributions support:
$ apt-get install bugs-everywhere
See the install page for more information and alternative methods.
If you have any problems with BE, you can look for matching bugs:
$ be --repo http://bugs.bugseverywhere.org/ list
If your bug isn’t listed, please open a new bug:
$ be --repo http://bugs.bugseverywhere.org/ new 'bug'
Created bug with ID bea/abc
$ be --repo http://bugs.bugseverywhere.org/ comment bea/def
<editor spawned for comments>
All of the following information elaborates on the command help text, which is stored in the code itself, and therefore more likely to be up to date. You can get a list of commands and topics with:
$ be help
Or see specific help on COMMAND with
$ be help COMMAND
for example:
$ be help init
will give help on the init command.
You’re happily coding in your Arch / Bazaar / Darcs / Git / Mercurial / Monotone versioned project and you discover a bug. You think, “Hmm, I’ll need a simple way to track these things”. This is where BE comes in. One of the benefits of distributed versioning systems is the ease of repository creation, and BE follows this trend. Just type:
$ be init
Using <VCS> for revision control.
BE repository initialized.
in your project’s root directory. This will create a .be directory containing the bug repository and notify your VCS so it will be versioned starting with your next commit. See:
$ be help init
for specific details about where the .be directory will end up if you call it from a directory besides your project’s root.
Inside the .be directory (among other things) there will be a long UUID directory. This is your bug directory. The idea is that you could keep several bug directories in the same repository, using one to track bugs, another to track roadmap issues, etc. See IDs for details. For BE itself, the bug directory is bea86499-824e-4e77-b085-2d581fa9ccab, which is why all the bug and comment IDs in this tutorial will start with bea/.
Create new bugs with:
$ be new <SUMMARY>
For example:
$ be new 'Missing demuxalizer functionality'
Created bug with ID bea/28f
If you are entering a bug reported by another person, take advantage of the --reporter option to give them credit:
$ be new --reporter 'John Doe <jdoe@example.com>' 'Missing whatsit...'
Created bug with ID bea/81a
See be help new for more details.
While the bug summary should include the appropriate keywords, it should also be brief. Unlike other bug trackers, the bug itself cannot contain a multi-line description. So you should probably add a comment immediately giving a more elaborate explanation of the problem so that the developer understands what you want and when the bug can be considered fixed.
Bugs are like little mailing lists, and you can comment on the bug itself or previous comments, attach files, etc. For example:
$ be comment abc/28f "Thoughts about demuxalizers..."
Created comment with ID abc/28f/97a
$ be comment abc/def/012 "Oops, I forgot to mention..."
Created comment with ID abc/28f/e88
Usually comments will be long enough that you’ll want to compose them in a text editor, not on the command line itself. Running be comment without providing a COMMENT argument will try to spawn an editor automatically (using your environment’s VISUAL or EDITOR, see Guide to Unix, Environmental Variables).
You can also pipe the comment body in on stdin, which is especially useful for binary attachments, etc.:
$ cat screenshot.png | be comment --content-type image/png bea/28f -
Created comment with ID bea/28f/35d
It’s polite to insert binary attachments under comments that explain the content and why you’re attaching it, so the above should have been:
$ be comment bea/28f "Whosit dissapears when you mouse-over whatsit."
Created comment with ID bea/28f/41d
$ cat screenshot.png | be comment --content-type image/png bea/28f/41d -
Created comment with ID bea/28f/35d
For more details, see be help comment.
Ok, you understand how to enter bugs, but how do you get that information back out? If you know the ID of the item you’re interested in (e.g. bug bea/28f), try:
$ be show bea/28f
ID : 28fb711c-5124-4128-88fe-a88a995fc519
Short name : bea/28f
Severity : minor
Status : open
Assigned :
Reporter :
Creator : ...
Created : ...
Missing demuxalizer functionality
--------- Comment ---------
Name: bea/28f/97a
From: ...
Date: ...
Thoughts about demuxalizers...
--------- Comment ---------
Name: bea/28f/e88
From: ...
Date: ...
Thoughts about demuxalizers...
--------- Comment ---------
Name: bea/28f/41d
From: ...
Date: ...
Whosit dissapears when you mouse-over whatsit.
--------- Comment ---------
Name: bea/28f/35d
From: ...
Date: ...
Content type image/png not printable. Try XML output instead
You can also get a single comment body, which is useful for extracting binary attachments:
$ be show --only-raw-body bea/28f/35d > screenshot.png
There is also an XML output format, which can be useful for emailing entries around, scripting BE, etc.:
$ be show --xml bea/35d
<?xml version="1.0" encoding="UTF-8" ?>
<be-xml>
...
If you don’t know which bug you’re interested in, you can query the whole bug directory:
$ be list
bea/28f:om: Missing demuxalizer functionality
bea/81a:om: Missing whatsit...
There are a whole slew of options for filtering the list of bugs. See be help list for details.
Often you will want to see what’s going on in another dev’s branch or remind yourself what you’ve been working on recently. All VCSs have some sort of diff command that shows what’s changed since revision XYZ. BE has it’s own command that formats the bug-repository portion of those changes in an easy-to-understand summary format. To compare your working tree with the last commit:
$ be diff
New bugs:
bea/01c:om: Need command output abstraction for flexible UIs
Modified bugs:
bea/343:om: Attach tests to bugs
Changed bug settings:
creator: None -> W. Trevor King <wking@drexel.edu>
Compare with a previous revision 1.1.0:
$ be diff 1.1.0
...
The format of revision names passed to diff will depend on your VCS. For Git, look to gitrevisions for inspiration.
Compare your BE branch with the trunk:
$ be diff --repo http://bugs.bugseverywhere.org/
There are several commands that allow to to set bug properties. They are all fairly straightforward, so we will merely point them out here, and refer you to be help COMMAND for more details.
You can also remove bugs you feel are no longer useful with be remove, and merge duplicate bugs with be merge.
Since BE bugs act as mini mailing lists, we provide be subscribe as a way to manage change notification. You can subscribe to all the changes with:
$ be subscribe --types all DIR
Subscribe only to bug creaton on bugseverywhere.org with:
$ be subscribe --server bugseverywhere.org --types new DIR
Subscribe to get all the details about bug bea/28f:
$ be subscribe --types new bea/28f
To unsubscribe, simply repeat the subscription command adding the --unsubscribe option, but be aware that it may take some time for these changes to propogate between distributed repositories. If you don’t feel confident in your ability to filter email, it’s best to only subscribe to the repository for which you have direct write access.
be set lets you configure a bug directory. You can set
For example, to set the current target to ‘1.2.3’:
$ be set target $(be target --resolve '1.2.3')
For serializing bug information (e.g. to email to a mailing list), use:
$ be show --xml bea/28f > bug.xml
This information can be imported into (another) bug directory via
$ be import-xml bug.xml
Also distributed with BE are some utilities to convert mailboxes into BE-XML (be-mail-to-xml) and convert BE-XML into mbox format for reading in your mail client.
To create a static dump of your bug directory, use:
$ be html
This is a fairly flexible command, see be help html for details. It works pretty well as the browsable part of a public interface using the Email Interface for interactive access.
Besides using BE to work directly with local VCS-based repositories, you can use:
$ be serve-storage
To serve a repository over HTTP. For example:
$ be serve-storage > server.log 2>&1 &
$ be --repo http://localhost:8000 list
Of course, be careful about serving over insecure networks, since malicous users could fill your disk with endless bugs, etc. You can disabled write access by using the --read-only option, which would make serving on a public network safer.
Serving the storage interface is flexible, but it can be inefficient. For example, a call to be list against a remote backend requires all bug information to be transfered over the wire. As a faster alternative, you may want to serve your repository at the command level:
$ be serve-commands > server.log 2>&1 &
$ be --server http://localhost:8000 list
Take a look at the server logs to get a feel for the bandwidth you’re saving! Serving commands over insecure networks is at least as dangerous as serving storage. Take appropriate precautions for your network.
Since BE uses internal storage drivers for its various backends, it seemed useful to provide a uniform interface to some of the common functionality. These commands are not intended to replace the usually much more powerful native VCS commands, but to provide an easy means of simple VCS-agnostic scripting for BE user interfaces, etc.
Currently, we only expose be commit, which commits all currently pending changes.