Merged be.restructure, major internal reorganization.

Added a bunch of classes to make the commands, user interfaces, and
storage backends more abstract and distinct.  This should make it much
easier to extend and maintain BE.

Features:
 * Directory restructured:
   becommands/ -> libbe/commands
   submods sorted by functionality.
 * Lots of new classes:
   Option, Argument, Command
   InputOutput, StorageCallbacks, UserInterface
   Storage
 * Consolidated ID handling in libbe.util.id
 * Transitioned VCS backends for Python-based VCSs from subprocess
   calss to internal python calls.

Plus the user-visible changes:
 * New bugdir/bug/comment ID format replaces old bug:comment format.
 * Deprecated support for `be diff` on Arch and Darcs <= 2.3.1.  A new
   backend abstraction (Storage) makes the former implementation
   ungainly.
 * Improved command completion.
 * Removed commands close, open, email_bugs, 
 * Flipped some arguments
   `be assign BUG-ID [ASSIGNEE]` -> `be status ASSIGNED BUG-ID ...`
   `be severity BUG-ID SEVERITY` -> `be severity SEVERITY BUG-ID ...`
   `be status BUG-ID STATUS` -> `be status STATUS BUG-ID ...`

In the merge:
  * Added 'commit' to list of pagerless commands.
  * Updated doc/README.dev

See
#bea86499-824e-4e77-b085-2d581fa9ccab/1100c966-9671-4bc6-8b68-6d408a910da1#
for a discussion of why the changes were made and some of the
difficulties en-route.

1 files changed, 64 insertions, 0 deletions

diff --git a/doc/README.dev b/doc/README.dev
new file mode 100644
index 0000000..a2b8d30
--- /dev/null
+++ b/doc/README.dev
@@ -0,0 +1,64 @@
+Extending BE
+============
+
+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.
+
+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
+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.
+
+
+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...
+
+
+Testing
+=======
+
+Run any tests in your module with
+  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).
+
+  $ 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 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.