8 Bugs Everywhere (BE) is a bugtracker built on distributed revision
9 control. The idea is to package the bug information with the source
10 code, so that developers working on the code can make appropriate
11 changes to the bug repository as they go. For example, by marking a
12 bug as "fixed" and applying the fixing changes in the same commit.
13 This makes it easy to see what's been going on in a particular branch
14 and helps keep the bug repository in sync with the code.
16 However, there are some differences compared to centralized
17 bugtrackers. Because bugs and comments can be created by several
18 users in parallel, they have globally unique :py:mod:`IDs
19 <libbe.util.id>` rather than numbers. There is also a
20 developer-friendly command-line_ interface to compliment the
21 user-friendly :doc:`web </http>` and :doc:`email </email>` interfaces.
22 This tutorial will focus on the command-line interface as the most
23 powerful, and leave the web and email interfaces to other documents.
25 .. _command-line: `Command-line interface`_
30 If your distribution packages BE, it will be easiest to use their package.
31 For example, most Debian-based distributions support::
33 $ apt-get install bugs-everywhere
35 See :doc:`the install page <install>` for more information and
41 If you have any problems with BE, you can look for matching bugs::
43 $ be --repo http://bugs.bugseverywhere.org/ list
45 If your bug isn't listed, please open a new bug::
47 $ be --repo http://bugs.bugseverywhere.org/ new 'bug'
48 Created bug with ID bea/abc
49 $ be --repo http://bugs.bugseverywhere.org/ comment bea/def
50 <editor spawned for comments>
53 Command-line interface
54 ======================
59 All of the following information elaborates on the command help text,
60 which is stored in the code itself, and therefore more likely to be up
61 to date. You can get a list of commands and topics with::
65 Or see specific help on ``COMMAND`` with
73 will give help on the ``init`` command.
78 You're happily coding in your Arch_ / Bazaar_ / Darcs_ / Git_ /
79 Mercurial_ / Monotone_ versioned project and you discover a bug.
80 You think, "Hmm, I'll need a simple way to track these things". This
81 is where BE comes in. One of the benefits of distributed versioning
82 systems is the ease of repository creation, and BE follows this trend.
86 Using <VCS> for revision control.
87 BE repository initialized.
89 in your project's root directory. This will create a ``.be``
90 directory containing the bug repository and notify your VCS so it will
91 be versioned starting with your next commit. See::
95 for specific details about where the ``.be`` directory will end up
96 if you call it from a directory besides your project's root.
98 .. _Arch: http://www.gnu.org/software/gnu-arch/
99 .. _Bazaar: http://bazaar.canonical.com/
100 .. _Darcs: http://darcs.net/
101 .. _Git: http://git-scm.com/
102 .. _Mercurial: http://mercurial.selenic.com/
103 .. _Monotone: http://www.monotone.ca/
105 Inside the ``.be`` directory (among other things) there will be a long
106 UUID_ directory. This is your bug directory. The idea is that you
107 could keep several bug directories in the same repository, using one
108 to track bugs, another to track roadmap issues, etc. See :py:mod:`IDs
109 <libbe.util.id>` for details. For BE itself, the bug directory is
110 ``bea86499-824e-4e77-b085-2d581fa9ccab``, which is why all the bug and
111 comment IDs in this tutorial will start with ``bea/``.
113 .. _UUID: http://en.wikipedia.org/wiki/Universally_Unique_Identifier
119 Create new bugs with::
125 $ be new 'Missing demuxalizer functionality'
126 Created bug with ID bea/28f
128 If you are entering a bug reported by another person, take advantage
129 of the ``--reporter`` option to give them credit::
131 $ be new --reporter 'John Doe <jdoe@example.com>' 'Missing whatsit...'
132 Created bug with ID bea/81a
134 See ``be help new`` for more details.
136 While the bug summary should include the appropriate keywords, it
137 should also be brief. Unlike other bug trackers, the bug itself cannot
138 contain a multi-line description. So you should probably add a comment
139 immediately giving a more elaborate explanation of the problem so that
140 the developer understands what you want and when the bug can be
146 Bugs are like little mailing lists, and you can comment on the bug
147 itself or previous comments, attach files, etc. For example::
149 $ be comment abc/28f "Thoughts about demuxalizers..."
150 Created comment with ID abc/28f/97a
151 $ be comment abc/def/012 "Oops, I forgot to mention..."
152 Created comment with ID abc/28f/e88
154 Usually comments will be long enough that you'll want to compose them
155 in a text editor, not on the command line itself. Running ``be
156 comment`` without providing a ``COMMENT`` argument will try to spawn
157 an editor automatically (using your environment's ``VISUAL`` or
158 ``EDITOR``, see `Guide to Unix, Environmental Variables`_).
160 .. _Guide to Unix, Environmental Variables:
161 http://en.wikibooks.org/wiki/Guide_to_Unix/Environment_Variables
163 You can also pipe the comment body in on stdin, which is especially
164 useful for binary attachments, etc.::
166 $ cat screenshot.png | be comment --content-type image/png bea/28f -
167 Created comment with ID bea/28f/35d
169 It's polite to insert binary attachments under comments that explain
170 the content and why you're attaching it, so the above should have
173 $ be comment bea/28f "Whosit dissapears when you mouse-over whatsit."
174 Created comment with ID bea/28f/41d
175 $ cat screenshot.png | be comment --content-type image/png bea/28f/41d -
176 Created comment with ID bea/28f/35d
178 For more details, see ``be help comment``.
183 Ok, you understand how to enter bugs, but how do you get that
184 information back out? If you know the ID of the item you're
185 interested in (e.g. bug bea/28f), try::
188 ID : 28fb711c-5124-4128-88fe-a88a995fc519
196 Missing demuxalizer functionality
197 --------- Comment ---------
202 Thoughts about demuxalizers...
203 --------- Comment ---------
208 Thoughts about demuxalizers...
209 --------- Comment ---------
214 Whosit dissapears when you mouse-over whatsit.
215 --------- Comment ---------
220 Content type image/png not printable. Try XML output instead
222 You can also get a single comment body, which is useful for extracting
225 $ be show --only-raw-body bea/28f/35d > screenshot.png
227 There is also an XML output format, which can be useful for emailing
228 entries around, scripting BE, etc.::
230 $ be show --xml bea/35d
231 <?xml version="1.0" encoding="UTF-8" ?>
238 If you *don't* know which bug you're interested in, you can query
239 the whole bug directory::
242 bea/28f:om: Missing demuxalizer functionality
243 bea/81a:om: Missing whatsit...
245 There are a whole slew of options for filtering the list of bugs. See
246 ``be help list`` for details.
251 Often you will want to see what's going on in another dev's branch or
252 remind yourself what you've been working on recently. All VCSs have
253 some sort of ``diff`` command that shows what's changed since revision
254 ``XYZ``. BE has its own command that formats the bug-repository
255 portion of those changes in an easy-to-understand summary format. To
256 compare your working tree with the last commit::
260 bea/01c:om: Need command output abstraction for flexible UIs
262 bea/343:om: Attach tests to bugs
263 Changed bug settings:
264 creator: None -> W. Trevor King <wking@drexel.edu>
266 Compare with a previous revision ``1.1.0``::
271 The format of revision names passed to ``diff`` will depend on your
272 VCS. For Git, look to gitrevisions_ for inspiration.
274 Compare your BE branch with the trunk::
276 $ be diff --repo http://bugs.bugseverywhere.org/
279 http://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html
284 There are several commands that allow to to set bug properties. They
285 are all fairly straightforward, so we will merely point them out here,
286 and refer you to ``be help COMMAND`` for more details.
288 * ``assign``, Assign an individual or group to fix a bug
289 * ``depend``, Add/remove bug dependencies
290 * ``due``, Set bug due dates
291 * ``status``, Change a bug's status level
292 * ``severity``, Change a bug's severity level
293 * ``tag``, Tag a bug, or search bugs for tags
294 * ``target``, Assorted bug target manipulations and queries
296 You can also remove bugs you feel are no longer useful with
297 ``be remove``, and merge duplicate bugs with ``be merge``.
302 Since BE bugs act as mini mailing lists, we provide ``be subscribe``
303 as a way to manage change notification. You can subscribe to all
306 $ be subscribe --types all DIR
308 Subscribe only to bug creaton on bugseverywhere.org with::
310 $ be subscribe --server bugseverywhere.org --types new DIR
312 Subscribe to get all the details about bug ``bea/28f``::
314 $ be subscribe --types new bea/28f
316 To unsubscribe, simply repeat the subscription command adding the
317 ``--unsubscribe`` option, but be aware that it may take some time for
318 these changes to propogate between distributed repositories. If you
319 don't feel confident in your ability to filter email, it's best to
320 only subscribe to the repository for which you have direct write
323 Managing bug directories
324 ------------------------
326 ``be set`` lets you configure a bug directory. You can set
329 The allowed active bug states and their descriptions.
330 * ``inactive_status``
331 The allowed inactive bug states and their descriptions.
333 The allowed bug severities and their descriptions.
335 The current project development target (bug UUID).
337 Space for an array of extra strings. You usually won't bother with
340 For example, to set the current target to '1.2.3'::
342 $ be set target $(be target --resolve '1.2.3')
347 For serializing bug information (e.g. to email to a mailing list), use::
349 $ be show --xml bea/28f > bug.xml
351 This information can be imported into (another) bug directory via
353 $ be import-xml bug.xml
355 Also distributed with BE are some utilities to convert mailboxes
356 into BE-XML (``be-mail-to-xml``) and convert BE-XML into mbox_
357 format for reading in your mail client.
359 .. _mbox: http://en.wikipedia.org/wiki/Mbox
364 To create a static dump of your bug directory, use::
368 This is a fairly flexible command, see ``be help html`` for details.
369 It works pretty well as the browsable part of a public interface using
370 the :doc:`email` for interactive access.
375 Besides using BE to work directly with local VCS-based repositories,
380 To serve a repository over HTTP. For example::
382 $ be serve-storage > server.log 2>&1 &
383 $ be --repo http://localhost:8000 list
385 Of course, be careful about serving over insecure networks, since
386 malicous users could fill your disk with endless bugs, etc. You can
387 disabled write access by using the ``--read-only`` option, which would
388 make serving on a public network safer.
390 Serving the storage interface is flexible, but it can be inefficient.
391 For example, a call to ``be list`` against a remote backend requires
392 all bug information to be transfered over the wire. As a faster
393 alternative, you may want to serve your repository at the command
396 $ be serve-commands > server.log 2>&1 &
397 $ be --server http://localhost:8000 list
399 Take a look at the server logs to get a feel for the bandwidth you're
400 saving! Serving commands over insecure networks is at least as
401 dangerous as serving storage. Take appropriate precautions for your
404 Driving the VCS through BE
405 --------------------------
407 Since BE uses internal storage drivers for its various backends, it
408 seemed useful to provide a uniform interface to some of the common
409 functionality. These commands are not intended to replace the usually
410 much more powerful native VCS commands, but to provide an easy means
411 of simple VCS-agnostic scripting for BE user interfaces, etc.
416 Currently, we only expose ``be commit``, which commits all currently