doc/tutorial.txt

   1 ********
   2 Tutorial
   3 ********
   4
   5 Introduction
   6 ============
   7
   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.
  15
  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.
  24
  25 .. _command-line: `Command-line interface`_
  26
  27 Installation
  28 ============
  29
  30 If your distribution packages BE, it will be easiest to use their package.
  31 For example, most Debian-based distributions support::
  32
  33     $ apt-get install bugs-everywhere
  34
  35 See :doc:`the install page <install>` for more information and
  36 alternative methods.
  37
  38 Bugs
  39 ====
  40
  41 If you have any problems with BE, you can look for matching bugs::
  42
  43     $ be --repo http://bugs.bugseverywhere.org/ list
  44
  45 If your bug isn't listed, please open a new bug::
  46
  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>
  51
  52
  53 Command-line interface
  54 ======================
  55
  56 Help
  57 ----
  58
  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::
  62
  63     $ be help
  64
  65 Or see specific help on ``COMMAND`` with
  66
  67     $ be help COMMAND
  68
  69 for example::
  70
  71     $ be help init
  72
  73 will give help on the ``init`` command.
  74
  75 Initialization
  76 --------------
  77
  78 You're happily coding in your Arch_ / Bazaar_ / Darcs_ / Git_ /
  79 Mercurial_ / Monotone_ versioned project and you discover a bug.
  80 "Hmm, I'll need a simple way to track these things", you think.  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.
  83 Just type::
  84
  85     $ be init
  86     Using <VCS> for revision control.
  87     BE repository initialized.
  88
  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::
  92
  93     $ be help init
  94
  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.
  97
  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/
 104
 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/``.
 112
 113 .. _UUID: http://en.wikipedia.org/wiki/Universally_Unique_Identifier
 114
 115
 116 Creating bugs
 117 -------------
 118
 119 Create new bugs with::
 120
 121     $ be new <SUMMARY>
 122
 123 For example::
 124
 125     $ be new 'Missing demuxalizer functionality'
 126     Created bug with ID bea/28f
 127
 128 If you are entering a bug reported by another person, take advantage
 129 of the ``--reporter`` option to give them credit::
 130
 131     $ be new --reporter 'John Doe <jdoe@example.com>' 'Missing whatsit...'
 132     Created bug with ID bea/81a
 133
 134 See ``be help new`` for more details.
 135
 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
 141 considered fixed.
 142
 143 Commenting on bugs
 144 ------------------
 145
 146 Bugs are like little mailing lists, and you can comment on the bug
 147 itself or previous comments, attach files, etc.  For example::
 148
 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
 153
 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`_).
 159
 160 .. _Guide to Unix, Environmental Variables:
 161    http://en.wikibooks.org/wiki/Guide_to_Unix/Environment_Variables
 162
 163 You can also pipe the comment body in on stdin, which is especially
 164 useful for binary attachments, etc.::
 165
 166     $ cat screenshot.png | be comment --content-type image/png bea/28f -
 167     Created comment with ID bea/28f/35d
 168
 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
 171 been::
 172
 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
 177
 178 For more details, see ``be help comment``.
 179
 180 Showing bugs
 181 ------------
 182
 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::
 186
 187     $ be show bea/28f
 188               ID : 28fb711c-5124-4128-88fe-a88a995fc519
 189       Short name : bea/28f
 190         Severity : minor
 191           Status : open
 192         Assigned :
 193         Reporter :
 194          Creator : ...
 195          Created : ...
 196     Missing demuxalizer functionality
 197     --------- Comment ---------
 198     Name: bea/28f/97a
 199     From: ...
 200     Date: ...
 201
 202     Thoughts about demuxalizers...
 203       --------- Comment ---------
 204       Name: bea/28f/e88
 205       From: ...
 206       Date: ...
 207
 208       Thoughts about demuxalizers...
 209     --------- Comment ---------
 210     Name: bea/28f/41d
 211     From: ...
 212     Date: ...
 213
 214     Whosit dissapears when you mouse-over whatsit.
 215       --------- Comment ---------
 216       Name: bea/28f/35d
 217       From: ...
 218       Date: ...
 219
 220       Content type image/png not printable.  Try XML output instead
 221
 222 You can also get a single comment body, which is useful for extracting
 223 binary attachments::
 224
 225     $ be show --only-raw-body bea/28f/35d > screenshot.png
 226
 227 There is also an XML output format, which can be useful for emailing
 228 entries around, scripting BE, etc.
 229
 230     $ be show --xml bea/35d
 231     <?xml version="1.0" encoding="UTF-8" ?>
 232     <be-xml>
 233     ...
 234
 235 Listing bugs
 236 ------------
 237
 238 If you *don't* know which bug you're interested in, you can query
 239 the whole bug directory::
 240
 241     $ be list
 242     bea/28f:om: Missing demuxalizer functionality
 243     bea/81a:om: Missing whatsit...
 244
 245 There are a whole slew of options for filtering the list of bugs.  See
 246 ``be help list`` for details.
 247
 248 Showing changes
 249 ---------------
 250
 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 it's 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::
 257
 258     $ be diff
 259     New bugs:
 260       bea/01c:om: Need command output abstraction for flexible UIs
 261     Modified bugs:
 262       bea/343:om: Attach tests to bugs
 263         Changed bug settings:
 264           creator: None -> W. Trevor King <wking@drexel.edu>
 265
 266 Compare with a previous revision ``480``::
 267
 268     $ be diff 480
 269     ...
 270
 271 Compare your BE branch with the trunk::
 272
 273     $ be diff --repo http://bugs.bugseverywhere.org/
 274
 275 Manipulating bugs
 276 -----------------
 277
 278 There are several commands that allow to to set bug properties.  They
 279 are all fairly straightforward, so we will merely point them out here,
 280 and refer you to ``be help COMMAND`` for more details.
 281
 282 * ``assign``, Assign an individual or group to fix a bug
 283 * ``depend``, Add/remove bug dependencies
 284 * ``due``, Set bug due dates
 285 * ``status``, Change a bug's status level
 286 * ``severity``, Change a bug's severity level
 287 * ``tag``, Tag a bug, or search bugs for tags
 288 * ``target``, Assorted bug target manipulations and queries
 289
 290 You can also remove bugs you feel are no longer useful with
 291 ``be remove``, and merge duplicate bugs with ``be merge``.
 292
 293 Subscriptions
 294 -------------
 295
 296 Since BE bugs act as mini mailing lists, we provide ``be subscribe``
 297 as a way to manage change notification.  You can subscribe to all
 298 the changes with::
 299
 300     $ be subscribe --types all DIR
 301
 302 Subscribe only to bug creaton on bugseverywhere.org with::
 303
 304     $ be subscribe --server bugseverywhere.org --types new DIR
 305
 306 Subscribe to get all the details about bug ``bea/28f``::
 307
 308     $ be subscribe --types new bea/28f
 309
 310 To unsubscribe, simply repeat the subscription command adding the
 311 ``--unsubscribe`` option, but be aware that it may take some time for
 312 these changes to propogate between distributed repositories.  If you
 313 don't feel confident in your ability to filter email, it's best to
 314 only subscribe to the repository for which you have direct write
 315 access.
 316
 317 Managing bug directories
 318 ------------------------
 319
 320 ``be set`` lets you configure a bug directory.  You can set
 321
 322 * ``active_status``
 323   The allowed active bug states and their descriptions.
 324 * ``inactive_status``
 325   The allowed inactive bug states and their descriptions.
 326 * ``severities``
 327   The allowed bug severities and their descriptions.
 328 * ``target``
 329   The current project development target (bug UUID).
 330 * ``extra_strings``
 331   Space for an array of extra strings.  You usually won't bother with
 332   this directly.
 333
 334 For example, to set the current target to '1.2.3'::
 335
 336     $ be set target $(be target --resolve '1.2.3')
 337
 338 Import XML
 339 ----------
 340
 341 For serializing bug information (e.g. to email to a mailing list), use::
 342
 343     $ be show --xml bea/28f > bug.xml
 344
 345 This information can be imported into (another) bug directory via
 346
 347     $ be import-xml bug.xml
 348
 349 Also distributed with BE are some utilities to convert mailboxes
 350 into BE-XML (``be-mail-to-xml``) and convert BE-XML into mbox_
 351 format for reading in your mail client.
 352
 353 .. _mbox: http://en.wikipedia.org/wiki/Mbox
 354
 355 Export HTML
 356 -----------
 357
 358 To create a static dump of your bug directory, use::
 359
 360     $ be html
 361
 362 This is a fairly flexible command, see ``be help html`` for details.
 363 It works pretty well as the browsable part of a public interface using
 364 the :doc:`email` for interactive access.
 365
 366 BE over HTTP
 367 ------------
 368
 369 Besides using BE to work directly with local VCS-based repositories,
 370 you can use::
 371
 372     $ be serve-storage
 373
 374 To serve a repository over HTTP.  For example::
 375
 376     $ be serve-storage > server.log 2>&1 &
 377     $ be --repo http://localhost:8000 list
 378
 379 Of course, be careful about serving over insecure networks, since
 380 malicous users could fill your disk with endless bugs, etc.  You can
 381 disabled write access by using the ``--read-only`` option, which would
 382 make serving on a public network safer.
 383
 384 Serving the storage interface is flexible, but it can be inefficient.
 385 For example, a call to ``be list`` against a remote backend requires
 386 all bug information to be transfered over the wire.  As a faster
 387 alternative, you may want to serve your repository at the command
 388 level::
 389
 390     $ be serve-commands > server.log 2>&1 &
 391     $ be --server http://localhost:8000 list
 392
 393 Take a look at the server logs to get a feel for the bandwidth you're
 394 saving!  Serving commands over insecure networks is at least as
 395 dangerous as serving storage.  Take appropriate precautions for your
 396 network.
 397
 398 Driving the VCS through BE
 399 --------------------------
 400
 401 Since BE uses internal storage drivers for its various backends, it
 402 seemed useful to provide a uniform interface to some of the common
 403 functionality.  These commands are not intended to replace the usually
 404 much more powerful native VCS commands, but to provide an easy means
 405 of simple VCS-agnostic scripting for BE user interfaces, etc.
 406
 407 Commit
 408 ~~~~~~
 409
 410 Currently, we only expose ``be commit``, which commits all currently
 411 pending changes.