Adding commands
---------------
-To write a plugin, you simply create a new file in the libbe/commands/
-directory. Take a look at one of the simpler plugins (e.g. remove.py)
-for an example of how that looks, and to start getting a feel for the
-libbe interface.
+To write a plugin, you simply create a new file in the
+``libbe/commands/`` directory. Take a look at one of the simpler
+plugins (e.g. ``remove.py``) for an example of how that looks, and to
+start getting a feel for the libbe interface.
-See libbe/commands/base.py for the definition of the important classes
-Option, Argument, Command, InputOutput, StorageCallbacks, and
-UserInterface classes. You'll be subclassing Command for your
-command, but all those classes will be important.
+See ``libbe/commands/base.py`` for the definition of the important
+classes ``Option``, ``Argument``, ``Command``, ``InputOutput``,
+``StorageCallbacks``, and ``UserInterface`` classes. You'll be
+subclassing ``Command`` for your command, but all those classes will
+be important.
Command completion
+~~~~~~~~~~~~~~~~~~
BE implements a general framework to make it easy to support command
completion for arbitrary plugins. In order to support this system,
-any of your completable Argument() instances (in your commands
-.options or .args) should be initialized with some valid
+any of your completable ``Argument()`` instances (in your command's
+``.options`` or ``.args``) should be initialized with some valid
completion_callback function. Some common cases are defined in
-libbe.command.util. If you need more flexibility, see
-libbe.command.list's "--sort" option for an example of extensions via
-libbe.command.util.Completer, or write a custom completion function
-from scratch.
+``libbe.command.util``. If you need more flexibility, see
+``libbe.command.list``'s ``--sort`` option for an example of
+extensions via ``libbe.command.util.Completer``, or write a custom
+completion function from scratch.
Adding user interfaces
----------------------
-Take a look at libbe/ui/command_line.py for an example. Basically
-you'll need to setup a UserInterface instance for running commands.
-More details to come after I write an HTML ui...
+Take a look at ``libbe/ui/command_line.py`` for an example. Basically
+you'll need to setup a ``UserInterface`` instance for running commands.
+More details to come after I write an HTML UI...
Testing
=======
-Run any tests in your module with
- be$ python test.py <python.module.name>
-for example
- be$ python test.py libbe.command.merge
+Run any tests in your module with::
-For a definition of "any tests", see test.py's add_module_tests()
-function.
+ be$ python test.py <python.module.name>
+
+for example:
+
+ be$ python test.py libbe.command.merge
+
+For a definition of "any tests", see ``test.py``'s
+``add_module_tests()`` function.
Profiling
=========
Find out which 20 calls take the most cumulative time (time of
-execution + childrens' times).
+execution + childrens' times)::
+
+ $ python -m cProfile -o profile be [command] [args]
+ $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)"
+
+It's often useful to toss::
- $ python -m cProfile -o profile be [command] [args]
- $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)"
+ import sys, traceback
+ print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:])
-It's often useful to toss a
- import sys, traceback
- print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:])
-into expensive functions (e.g. libbe.util.subproc.invoke()), if you're
-not sure why they're being called.
+into expensive functions (e.g. ``libbe.util.subproc.invoke()``) if
+you're not sure why they're being called.
-TODO
+Tutorial
+========
+
+Introduction
+------------
+
+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.
+
+.. _command-line: `Command-line interface`_
+.. _web: ../doc/tutorial-html
+.. _email: ../doc/tutorial-email
+
+Installation
+------------
+
+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
+
+Bugs
+----
+
+If you have any problems with BE, you can look for matching bugs::
+
+ $ be --repo http://bugseverywhere.org/bugs list
+
+If your bug isn't listed, please open a new bug::
+
+ $ be --repo http://bugseverywhere.org/bugs new 'bug'
+ Created bug with ID bea/abc
+ $ be --repo http://bugseverywhere.org/bugs comment bea/def
+ <editor spawned for comments>
+
+
+Command-line interface
+----------------------
+
+Help
+~~~~
+
+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.
+
+Initialization
+~~~~~~~~~~~~~~
+
+You're happily coding in your Arch_ / Bazaar_ / Darcs_ / Git_ /
+Mercurial_ versioned project and you discover a bug. "Hmm, I'll need
+a simple way to track these things", you think. 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.
+
+.. _Arch: http://www.gnu.org/software/gnu-arch/
+.. _Bazaar: http://bazaar.canonical.com/
+.. _Darcs: http://darcs.net/
+.. _Git: http://git-scm.com/
+.. _Mercurial: http://mercurial.selenic.com/
+
+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/``.
+
+.. _UUID: http://en.wikipedia.org/wiki/Universally_Unique_Identifier
+
+
+Creating bugs
+~~~~~~~~~~~~~
+
+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. 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.
+
+Commenting on bugs
+~~~~~~~~~~~~~~~~~~
+
+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`_).
+
+.. _Guide to Unix, Environmental Variables:
+ http://en.wikibooks.org/wiki/Guide_to_Unix/Environment_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``.
+
+Showing bugs
+~~~~~~~~~~~~
+
+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>
+ ...
+
+Listing bugs
+~~~~~~~~~~~~
+
+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.
+
+Showing changes
+~~~~~~~~~~~~~~~
+
+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 ``480``::
+
+ $ be diff 480
+ ...
+
+Compare your BE branch with the trunk::
+
+ $ be diff --repo http://bugseverywhere.org/bugs/
+
+Manipulating bugs
+~~~~~~~~~~~~~~~~~
+
+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.
+
+* ``assign``, Assign an individual or group to fix a bug
+* ``depend``, Add/remove bug dependencies
+* ``due``, Set bug due dates
+* ``status``, Change a bug's status level
+* ``severity``, Change a bug's severity level
+* ``tag``, Tag a bug, or search bugs for tags
+* ``target``, Assorted bug target manipulations and queries
+
+You can also remove bugs you feel are no longer useful with
+``be remove``, and merge duplicate bugs with ``be merge``.
+
+Subscriptions
+~~~~~~~~~~~~~
+
+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.
+
+Managing bug directories
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``be set`` lets you configure a bug directory. You can set
+
+* ``active_status``
+ The allowed active bug states and their descriptions.
+* ``inactive_status``
+ The allowed inactive bug states and their descriptions.
+* ``severities``
+ The allowed bug severities and their descriptions.
+* ``target``
+ The current project development target (bug UUID).
+* ``extra_strings``
+ Space for an array of extra strings. You usually won't bother with
+ this directly.
+
+For example, to set the current target to '1.2.3'::
+
+ $ be set target $(be target --resolve '1.2.3')
+
+Import XML
+~~~~~~~~~~
+
+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.
+
+.. _mbox: http://en.wikipedia.org/wiki/Mbox
+
+Export HTML
+~~~~~~~~~~~
+
+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.
+
+BE over HTTP
+~~~~~~~~~~~~
+
+Besides using BE to work directly with local VCS-based repositories,
+you can use::
+
+ $ be serve
+
+To serve a repository over HTTP. For example::
+
+ $ be serve > 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
+dissable write access by using the ``--read-only`` option, which would
+make serving on a public network safer.
+
+Driving the VCS through BE
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+
+IDs
+---
+
+Format
+~~~~~~
+
+BE IDs are formatted::
+
+ <bug-directory>[/<bug>[/<comment>]]
+
+where each ``<..>`` is a UUID. For example::
+
+ bea86499-824e-4e77-b085-2d581fa9ccab/3438b72c-6244-4f1d-8722-8c8d41484e35
+
+refers to bug ``3438b72c-6244-4f1d-8722-8c8d41484e35`` which is
+located in bug directory ``bea86499-824e-4e77-b085-2d581fa9ccab``.
+This is a bit of a mouthful, so you can truncate each UUID so long as
+it remains unique. For example::
+
+ bea/343
+
+If there were two bugs ``3438...`` and ``343a...`` in ``bea``, you'd
+have to use::
+
+ bea/3438
+
+BE will only truncate each UUID down to three characters to slightly
+future-proof the short user ids. However, if you want to save keystrokes
+and you *know* there is only one bug directory, feel free to truncate
+all the way to zero characters::
+
+ /3438
+
+Cross references
+~~~~~~~~~~~~~~~~
+
+To refer to other bug-directories/bugs/comments from bug comments, simply
+enclose the ID in pound signs (``#``). BE will automatically expand the
+truncations to the full UUIDs before storing the comment, and the reference
+will be appropriately truncated (and hyperlinked, if possible) when the
+comment is displayed.
+
+Scope
+~~~~~
+
+Although bug and comment IDs always appear in compound references,
+UUIDs at each level are globally unique. For example, comment
+``bea/343/ba96f1c0-ba48-4df8-aaf0-4e3a3144fc46`` will *only* appear
+under ``bea/343``. The prefix (``bea/343``) allows BE to reduce
+caching global comment-lookup tables and enables easy error messages
+("I couldn't find ``bea/343/ba9`` because I don't know where the
+``bea`` bug directory is located").
========
The interactive email interface to Bugs Everywhere (BE) attempts to
-provide a Debian-bug-tracking-system-style interface to a BE
+provide a `Debian-bug-tracking-system-style`_ interface to a BE
repository. Users can mail in bug reports, comments, or control
requests, which will be committed to the served repository.
Developers can then pull the changes they approve of from the served
repository into their other repositories and push updates back onto
the served repository.
-For details about the Debian bug tracking system that inspired this
-interface, see http://www.debian.org/Bugs .
+.. _Debian-bug-tracking-system-style: http://www.debian.org/Bugs
Architecture
============
In order to reduce setup costs, the entire interface can piggyback on
an existing email address, although from a security standpoint it's
probably best to create a dedicated user. Incoming email is filtered
-by procmail, with matching emails being piped into be-handle-mail for
-execution.
-
-Once be-handle-mail receives the email, the parsing method is selected
-according to the subject tag that procmail used grab the email in the
-first place. There are four parsing styles:
- Style Subject
- creating bugs [be-bug:submit] new bug summary
- commenting on bugs [be-bug:<bug-id>] commit message
- control [be-bug] commit message
-These are analogous to submit@bugs.debian.org, nnn@bugs.debian.org,
-and control@bugs.debian.org respectively.
+by procmail, with matching emails being piped into ``be-handle-mail``
+for execution.
+
+Once ``be-handle-mail`` receives the email, the parsing method is
+selected according to the subject tag that procmail used grab the
+email in the first place. There are four parsing styles:
+
+ +--------------------+----------------------------------+
+ | Style | Subject |
+ +====================+==================================+
+ | creating bugs | [be-bug:submit] new bug summary |
+ +--------------------+----------------------------------+
+ | commenting on bugs | [be-bug:<bug-id>] commit message |
+ +--------------------+----------------------------------+
+ | control | [be-bug] commit message |
+ +--------------------+----------------------------------+
+
+These are analogous to ``submit@bugs.debian.org``,
+``nnn@bugs.debian.org``, and ``control@bugs.debian.org`` respectively.
Creating bugs
=============
This interface creates a bug whose summary is given by the email's
post-tag subject. The body of the email must begin with a
-pseudo-header containing at least the "Version" field. Anything after
-the pseudo-header and before a line starting with '--' is, if present,
-attached as the bug's first comment.
+pseudo-header containing at least the ``Version`` field. Anything after
+the pseudo-header and before a line starting with ``--`` is, if present,
+attached as the bug's first comment.::
From jdoe@example.com Fri Apr 18 12:00:00 2008
From: John Doe <jdoe@example.com>
Severity: minor
Someone should write up a series of test emails to send into
- be-handle mail so we can test changes quickly without having to
+ be-handle-mail so we can test changes quickly without having to
use procmail.
--
Goofy tagline not included.
-Available pseudo-headers are Version, Reporter, Assign, Depend,
-Severity, Status, Tag, and Target.
+Available pseudo-headers are ``Version``, ``Reporter``, ``Assign``,
+``Depend``, ``Severity``, ``Status``, ``Tag``, and ``Target``.
Commenting on bugs
==================
This interface appends a comment to the bug specified in the subject
tag. The the first non-multipart body is attached with the
-appropriate content-type. In the case of "text/plain" contents,
-anything following a line starting with '--' is stripped.
+appropriate content-type. In the case of ``text/plain`` contents,
+anything following a line starting with ``--`` is stripped.::
From jdoe@example.com Fri Apr 18 12:00:00 2008
From: John Doe <jdoe@example.com>
================
This interface consists of a list of allowed be commands, with one
-command per line. Blank lines and lines beginning with '#' are
-ignored, as well anything following a line starting with '--'. All
+command per line. Blank lines and lines beginning with ``#`` are
+ignored, as well anything following a line starting with ``--``. All
the listed commands are executed in order and their output returned.
The commands are split into arguments with the POSIX-compliant
-shlex.split().
+shlex.split().::
From jdoe@example.com Fri Apr 18 12:00:00 2008
From: John Doe <jdoe@example.com>
Example emails
==============
-Take a look at my interfaces/email/interactive/examples for some
+Take a look at ``interfaces/email/interactive/examples`` for some
more examples.
Procmail rules
==============
-The file _procmailrc as it stands is fairly appropriate for as a
-dedicated user's ~/.procmailrc. It forwards matching mail to
-be-handle-mail, which should be installed somewhere in the user's
-path. All non-matching mail is dumped into /dev/null. Everything
-procmail does will be logged to ~/be-mail/procmail.log.
+The file ``_procmailrc`` as it stands is fairly appropriate for as a
+dedicated user's ``~/.procmailrc``. It forwards matching mail to
+``be-handle-mail``, which should be installed somewhere in the user's
+path. All non-matching mail is dumped into ``/dev/null``. Everything
+procmail does will be logged to ``~/be-mail/procmail.log``.
If you're piggybacking the interface on top of an existing account,
-you probably only need to add the be-handle-mail stanza to your
-existing ~/.procmailrc, since you will still want to receive non-bug
-emails.
+you probably only need to add the ``be-handle-mail`` stanza to your
+existing ``~/.procmailrc``, since you will still want to receive
+non-bug emails.
-Note that you will probably have to add a
- --be-dir /path/to/served/repository
-option to the be-handle-mail invocation so it knows what repository to
+Note that you will probably have to add a::
+
+ --repo /path/to/served/repository
+
+option to the ``be-handle-mail`` invocation so it knows what repository to
serve.
Multiple repositories may be served by the same email address by adding
-multiple be-handle-mail stanzas, each matching a different tag, for
-example the "[be-bug" portion of the stanza could be "[projectX-bug",
-"[projectY-bug", etc. If you change the base tag, be sure to add a
- --tag-base "projectX-bug"
-or equivalent to your be-handle-mail invocation.
+multiple ``be-handle-mail`` stanzas, each matching a different tag, for
+example the ``[be-bug`` portion of the stanza could be ``[projectX-bug``,
+``[projectY-bug``, etc. If you change the base tag, be sure to add a::
+
+ --tag-base "projectX-bug"
+
+or equivalent to your ``be-handle-mail`` invocation.
Testing
=======
-Send test emails in to be-handle-mail with something like
- cat examples/blank | ./be-handle-mail -o -l - -a
+Send test emails in to ``be-handle-mail`` with something like::
+
+ cat examples/blank | ./be-handle-mail -o -l - -a
projects / be.git / commitdiff