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 :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 :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 been
 171
 172     $ be comment bea/28f "Whosit dissapears when you mouse-over whatsit."
 173     Created comment with ID bea/28f/41d
 174     $ cat screenshot.png | be comment --content-type image/png bea/28f/41d
 175     Created comment with ID bea/28f/35d
 176
 177 For more details, see ``be help comment``.
 178
 179 Showing bugs
 180 ------------
 181
 182 Ok, you understand how to enter bugs, but how do you get that
 183 information back out?  If you know the ID of the item you're
 184 interested in (e.g. bug bea/28f), try::
 185
 186     $ be show bea/28f
 187               ID : 28fb711c-5124-4128-88fe-a88a995fc519
 188       Short name : bea/28f
 189         Severity : minor
 190           Status : open
 191         Assigned :
 192         Reporter :
 193          Creator : ...
 194          Created : ...
 195     Missing demuxalizer functionality
 196     --------- Comment ---------
 197     Name: bea/28f/97a
 198     From: ...
 199     Date: ...
 200
 201     Thoughts about demuxalizers...
 202       --------- Comment ---------
 203       Name: bea/28f/e88
 204       From: ...
 205       Date: ...
 206
 207       Thoughts about demuxalizers...
 208     --------- Comment ---------
 209     Name: bea/28f/41d
 210     From: ...
 211     Date: ...
 212
 213     Whosit dissapears when you mouse-over whatsit.
 214       --------- Comment ---------
 215       Name: bea/28f/35d
 216       From: ...
 217       Date: ...
 218
 219       Content type image/png not printable.  Try XML output instead
 220
 221 You can also get a single comment body, which is useful for extracting
 222 binary attachments::
 223
 224     $ be show --only-raw-body bea/28f/35d > screenshot.png
 225
 226 There is also an XML output format, which can be useful for emailing
 227 entries around, scripting BE, etc.
 228
 229     $ be show --xml bea/35d
 230     <?xml version="1.0" encoding="UTF-8" ?>
 231     <be-xml>
 232     ...
 233
 234 Listing bugs
 235 ------------
 236
 237 If you *don't* know which bug you're interested in, you can query
 238 the whole bug directory::
 239
 240     $ be list
 241     bea/28f:om: Missing demuxalizer functionality
 242     bea/81a:om: Missing whatsit...
 243
 244 There are a whole slew of options for filtering the list of bugs.  See
 245 ``be help list`` for details.
 246
 247 Showing changes
 248 ---------------
 249
 250 Often you will want to see what's going on in another dev's branch or
 251 remind yourself what you've been working on recently.  All VCSs have
 252 some sort of ``diff`` command that shows what's changed since revision
 253 ``XYZ``.  BE has it's own command that formats the bug-repository
 254 portion of those changes in an easy-to-understand summary format.  To
 255 compare your working tree with the last commit::
 256
 257     $ be diff
 258     New bugs:
 259       bea/01c:om: Need command output abstraction for flexible UIs
 260     Modified bugs:
 261       bea/343:om: Attach tests to bugs
 262         Changed bug settings:
 263           creator: None -> W. Trevor King <wking@drexel.edu>
 264
 265 Compare with a previous revision ``480``::
 266
 267     $ be diff 480
 268     ...
 269
 270 Compare your BE branch with the trunk::
 271
 272     $ be diff --repo http://bugs.bugseverywhere.org/
 273
 274 Manipulating bugs
 275 -----------------
 276
 277 There are several commands that allow to to set bug properties.  They
 278 are all fairly straightforward, so we will merely point them out here,
 279 and refer you to ``be help COMMAND`` for more details.
 280
 281 * ``assign``, Assign an individual or group to fix a bug
 282 * ``depend``, Add/remove bug dependencies
 283 * ``due``, Set bug due dates
 284 * ``status``, Change a bug's status level
 285 * ``severity``, Change a bug's severity level
 286 * ``tag``, Tag a bug, or search bugs for tags
 287 * ``target``, Assorted bug target manipulations and queries
 288
 289 You can also remove bugs you feel are no longer useful with
 290 ``be remove``, and merge duplicate bugs with ``be merge``.
 291
 292 Subscriptions
 293 -------------
 294
 295 Since BE bugs act as mini mailing lists, we provide ``be subscribe``
 296 as a way to manage change notification.  You can subscribe to all
 297 the changes with::
 298
 299     $ be subscribe --types all DIR
 300
 301 Subscribe only to bug creaton on bugseverywhere.org with::
 302
 303     $ be subscribe --server bugseverywhere.org --types new DIR
 304
 305 Subscribe to get all the details about bug ``bea/28f``::
 306
 307     $ be subscribe --types new bea/28f
 308
 309 To unsubscribe, simply repeat the subscription command adding the
 310 ``--unsubscribe`` option, but be aware that it may take some time for
 311 these changes to propogate between distributed repositories.  If you
 312 don't feel confident in your ability to filter email, it's best to
 313 only subscribe to the repository for which you have direct write
 314 access.
 315
 316 Managing bug directories
 317 ------------------------
 318
 319 ``be set`` lets you configure a bug directory.  You can set
 320
 321 * ``active_status``
 322   The allowed active bug states and their descriptions.
 323 * ``inactive_status``
 324   The allowed inactive bug states and their descriptions.
 325 * ``severities``
 326   The allowed bug severities and their descriptions.
 327 * ``target``
 328   The current project development target (bug UUID).
 329 * ``extra_strings``
 330   Space for an array of extra strings.  You usually won't bother with
 331   this directly.
 332
 333 For example, to set the current target to '1.2.3'::
 334
 335     $ be set target $(be target --resolve '1.2.3')
 336
 337 Import XML
 338 ----------
 339
 340 For serializing bug information (e.g. to email to a mailing list), use::
 341
 342     $ be show --xml bea/28f > bug.xml
 343
 344 This information can be imported into (another) bug directory via
 345
 346     $ be import-xml bug.xml
 347
 348 Also distributed with BE are some utilities to convert mailboxes
 349 into BE-XML (``be-mail-to-xml``) and convert BE-XML into mbox_
 350 format for reading in your mail client.
 351
 352 .. _mbox: http://en.wikipedia.org/wiki/Mbox
 353
 354 Export HTML
 355 -----------
 356
 357 To create a static dump of your bug directory, use::
 358
 359     $ be html
 360
 361 This is a fairly flexible command, see ``be help html`` for details.
 362 It works pretty well as the browsable part of a public interface using
 363 the :doc:`email` for interactive access.
 364
 365 BE over HTTP
 366 ------------
 367
 368 Besides using BE to work directly with local VCS-based repositories,
 369 you can use::
 370
 371     $ be serve-storage
 372
 373 To serve a repository over HTTP.  For example::
 374
 375     $ be serve-storage > server.log 2>&1 &
 376     $ be --repo http://localhost:8000 list
 377
 378 Of course, be careful about serving over insecure networks, since
 379 malicous users could fill your disk with endless bugs, etc.  You can
 380 disabled write access by using the ``--read-only`` option, which would
 381 make serving on a public network safer.
 382
 383 Serving the storage interface is flexible, but it can be inefficient.
 384 For example, a call to ``be list`` against a remote backend requires
 385 all bug information to be transfered over the wire.  As a faster
 386 alternative, you may want to serve your repository at the command
 387 level::
 388
 389     $ be serve-commands > server.log 2>&1 &
 390     $ be --server http://localhost:8000 list
 391
 392 Take a look at the server logs to get a feel for the bandwidth you're
 393 saving!  Serving commands over insecure networks is at least as
 394 dangerous as serving storage.  Take appropriate precautions for your
 395 network.
 396
 397 Driving the VCS through BE
 398 --------------------------
 399
 400 Since BE uses internal storage drivers for its various backends, it
 401 seemed useful to provide a uniform interface to some of the common
 402 functionality.  These commands are not intended to replace the usually
 403 much more powerful native VCS commands, but to provide an easy means
 404 of simple VCS-agnostic scripting for BE user interfaces, etc.
 405
 406 Commit
 407 ~~~~~~
 408
 409 Currently, we only expose ``be commit``, which commits all currently
 410 pending changes.