doc:tutorial: fix ReST formatting for first `be comment` example

doc:install: mention that we *do* post releases now

doc:install: mention that PyYAML is now optional

storage:util:upgrade: make yaml import optional (unless it isn't)

Importing `yaml` may fail (if the user doesn't have PyYAML installed),
but don't die until we need to use it.  This way users without the old
YAML formats on disk can run BE without installing PyYAML.

command: use mapfiles (JSON) instead of YAML for the command server

storage:util:mapfile: add `context` argument to generate()

doc/install: fix paragraph indentation in man page installation discussion

doc/install: point out relevant Debian bugs in a comment

doc:install: fix dependency table ReST formatting

The header had been broken by

  commit f174d8943c2edea25306ab522c27f69bbebd0be3
  Author: W. Trevor King <wking@tremily.us>
  Date:   Thu May 10 08:56:02 2012 -0400

    Update CherryPy dependency package to python-cherrypy3 on Debian.

doc:index: mention that in-branch-bugs are not the only way

doc: clean up top level module docstrings

libbe:bugdir: avoid SimpleBugDir is not a item name

This happens because SimpleBugDir is not defined if libbe.TESTING is
not set before importing libbe.bugdir.

doc: update :attr: to :py:attr: for modern Sphinx.

doc: update :data: to :py:data: for modern Sphinx.

doc: update :meth: to :py:meth: for modern Sphinx.

doc:config: use :file: to markup filenames.

doc: update :class: to :py:class: for modern Sphinx.

storage:vcs:base: avoid `is not a item name` Sphinx error.

doc:conf: use `version (date)` in Sphinx docs

Since

  commit bed7587fe4910f8e4b892a09675279c5a4ab5484
  Author: W. Trevor King <wking@tremily.us>
  Date:   Thu Oct 25 19:07:09 2012 -0400

    version: use abbreviated SHA instead of  explicit _VERSION in master branch

the version SHA will either be explicit in version(), or version()
will return a release tag.  This makes the long SHA in the Sphinx docs
unnecessary, so we can replace it with the more interesting commit
date.

doc: update :mod: to :py:mod: for modern Sphinx.

doc: update :func: to :py:func: for modern Sphinx.

storage:util:config: path() now defaults to ~/.config/bugs-everywhere

Add a documentation section discussing the config file, respect
XDG_CONFIG_HOME, and add BE_CONFIG_PATH.

release.py: strip trailing whitespace from ChangeLog.

release.py: sign tags when cutting releases.

release.py: use current Python executable for ./be invocation

This allow you to cut a release where your system Python is not
compatible with be.  For example:

  $ python --version
  Python 3.2.3
  $ python2.7 ./release.py 1.1.0

setup.py: flesh out setup in preparation for PyPI posting

setup.py: change setup.py name to something more PyPI friendly.

setup.py: don't put the date in the setup.py version (PyPI gets mad).

version: use abbreviated SHA instead of  explicit _VERSION in master branch

Only official releases get a version number, which should help avoid
confusion.  If you're running a live checkout, you shouldn't be scared
off by SHAs.

release.py: pull main code into main().

update-copyright: update to the python3 branch.

release.py: remove dependency on deprecated libbe.subproc.Pipe

Pipe has been gone since:

  commit f1ae4b7f3fea6fb78a54ee5073aee648a3d73179
  Author: W. Trevor King <wking@drexel.edu>
  Date:   Sat Feb 25 11:16:01 2012 -0500

    Remove util.subproc.Pipe, as we no longer use it in BE.

interfaces:web:web: use bugdir_bug_comment_from_user_id() in CFBE.

This gets CFBE working with:

  commit 4db1a045a0606bead191a563abc54dfa8352efe0
  Author: W. Trevor King <wking@tremily.us>
  Date:   Wed Aug 29 23:26:17 2012 -0400

    Rewrite commands to use bugdirs instead of a single bugdir.

I'm not sure how much work it would take to rewrite CFBE to use
multiple bugdirs.

bugdir|bug|comment: update default settings string to be value JSON.

storage:util:mapfile: fix YAML -> JSON in docstrings.

This should have been done back in:

  commit a95915c6c7d6a4e29c1e5547580e0c1fed2467e1
  Author: W. Trevor King <wking@tremily.us>
  Date:   Mon Sep 17 08:14:21 2012 -0400

    storage:util:mapfile: convert YAML settings to JSON.

I also add an empty-settings generation as a sanity check.

setup.py: make libbe._version optional.

Thanks to Timmie for pointing this out:

From: Timmie <timmichelsen@gmx-topmail.de>
Date: Thu, 25 Oct 2012 09:42:23 +0000 (UTC)
Subject: Re: [Be-devel] NotImplementedError with Bazaar

...
I notices the following glichtes during the install:

D:\be-be-master\be-be>python setup.py install
WARNING:root:unable to import libbe._version: No module named _version
Traceback (most recent call last):
  File "setup.py", line 6, in <module>
    from libbe import _version, version
ImportError: cannot import name _version
...

.update-copyright.conf: update to pipe separators.

This brings the config file up to speed with the following
update-copyright commit:

  commit 3c68a1a48419d8b2bbc2ce0e7f1700b996ec30e9
  Author: W. Trevor King <wking@tremily.us>
  Date:   Fri Oct 19 21:52:48 2012 -0400

    project: for consistency, also separate ignored paths with pipes

Ran update-copyright.py.

.mailmap: consilidate Niall Douglas' addresses.

update-copyright: update to current update-copyright (v0.4+).

doc:tutorial: fix typos in the attachment examples.

I wrote the actual patch, but Nicolas gave pretty unambiguous
directions, so I'm making him the author.

On Wed, Sep 19, 2012 at 11:03:39AM -0400, Nicolas Bigaouette wrote:
> Hi all,
>
> I'm trying out Bugs Everywhere, pretty neat!
>
> Reading the documentation, I see it's possible to add attachment to the bug
> report. The "commenting on bugs" section of the tutorial[1] gives the
> command for the attachment:
>
> > $ cat screenshot.png | be comment --content-type image/png bea/28f
> >
> or the following to reply to a specific comment:
>
> > $ be comment bea/28f “Whosit dissapears when you mouse-over whatsit.”
> > $ cat screenshot.png | be comment --content-type image/png bea/28f/41d
> >
>
> Both these commands fail as they will try to open the editor for entering
> the comment.
>
> The fix is simply to append a single dash "-" at the end of the attachment
> command to tell "be comment" to read the comment from stdin (see "be help
> comment").
>
> Also, the second example has not the same formatting as the first one. The
> first one seems to have a "code" formatting, while the second is just
> indented without any line breaks.
>
> Thanks!
>
> Nicolas
>
> [1] http://docs.bugseverywhere.org/tutorial.html#commenting-on-bugs

storage:vcs:git: check for existence of pygit2.__version__.

Now that my pull request has been accepted, we can be fairly confident
that future releases of pygit2 will expose this attribute.  The
accepted patch was a bit different from the original submission:

Add 'pygit2.__version__' for easy access from client software.
  https://github.com/libgit2/pygit2/pull/128
  commit f10d2b7b3f0c67d81b175326035e4813420156bd

command:html: convert -moz-border-radius to border-radius.

border-radius and friends are standard CSS3 [1].

[1]: http://www.w3.org/TR/css3-background/#the-border-radius

command.html: display "Target:" detail for bugs with targets.

command:html: fix two auto% -> auto typos in CSS.

These were introduced in

  commit d61d54ce33022f0613c5e19e2f52be4ab77c4664
  Author: Gianluca Montecchi <gian@grys.it>
  Date:   Mon Jan 24 22:47:32 2011 +0100

    New html output for html command

and propogated in

  commit 5b6be7a511670cdf1961d13040cddcb34e70b8a1
  Author: W. Trevor King <wking@drexel.edu>
  Date:   Sun Apr 17 02:41:07 2011 -0400

    Rework `be html` to use Jinja2 templates.

bea864: upgrade to Bugs Everywhere Directory v1.5 (YAML -> JSON).

storage:util:mapfile: convert YAML settings to JSON.

This is faster and still readable.  I also add an upgrader to convert
bug directories from:
  Bugs Everywhere Directory v1.4
to:
  Bugs Everywhere Directory v1.5
but I haven't upgraded the local bugdir yet.

storage:vcs:git: move Git to ExecGit and add PygitGit using pygit2.

If `pygit2` is installed, use it (via PygitGit) rather than calling
the stand-alone `git` executable for all the Git (via ExecGit) for all
the Git storage stuff.  This saves one serializing/deserializing and
process setup/teardown.  I timed each test suite by commenting out one
of the `make_vcs_testcase_subclasses()` calls at the end of `git.py`
and running

  $ time python test.py libbe.storage.vcs.git

The ExecGit tests ran in 13.7s and the PygitGit tests ran in 3.6s for
a 3.8x speedup.

I had to stretch pygit2 a bit to get a clean fit, so if you want to
test this, you'll need to build pygit2 with the following merge
requests:

  Add 'pygit2.__version__' for easy access from client software.
    https://github.com/libgit2/pygit2/pull/128
    commit 0238fb72dfdf2a2308f2da347717cbaafddc4b83
  signature: Add keyword argument parsing to Signature().
    https://github.com/libgit2/pygit2/pull/129
    commit c934858b629f40221406f34166dd77e881b9d5fd
  repository: add Repository.revparse_single()
    https://github.com/libgit2/pygit2/pull/131
    commit 3afdc8b2f59ed137531671fedde36f3a39cbcc9d

storage:vcs:base: fix _gets_ -> _get_ typo in test_gets_existing_user_id.

VCS_get_user_id_TestCase.test_gets_existing_user_id is now
VCS_get_user_id_TestCase.test_get_existing_user_id

storage:vcs:base: fix realtive -> relative typo in _u_abspath docstring.

command:html: add --strip-email option.

command:html: oops, use default arguments for 'notify' and 'auth'.

command:html: fix super(HTML. self) -> super(HTML, self).

ui:command_line: use `be help server` for help with `--server`.

Use the recently created topic, which provides more details than the
`serve-commands` help message.

ui:command_line: display help.TOPICS during `be help`.

command:help: add `repo` and `server` topics.

command:help: match against command names (not module names).

ui:command_line: use command names in command-list help message.

The old implementation used module names.  For example:
  command name: import-xml
  module name:  import_xml

ui:command_line: add 'html' command to no-pager commands.

Also rename 'serve' -> 'serve-storaage'.

This catches the server version up with:

  commit 0336db8d4052a319f1d959a33fc847814551e3f8
  Author: W. Trevor King <wking@tremily.us>
  Date:   Wed Aug 29 23:55:37 2012 -0400

    command:serve-storage: rename `be serve` -> `be serve-storage`.

util:wsgi: WSGITestCase should not subclass WSGICaller.

The old implementation caused a number of unittest errors.

This commit adds a WSGICaller instance as WSGITestCase.caller, and
provides a wrapper .getURL method which copies the
status/headers/etc. from the caller back into the WSGITestCase.

command:html: rewrite as a libbe.util.wsgi.ServerCommand.

Now `be html` defaults to serving the BE repo live.  With the
`--export-html` option, it reverts to the earlier static dump
behaviour.

This will make it easier for others to embed a read-only HTML server
in their own app (e.g. as a gitorious issue tracker).

util:wsgi: Pull WSGICaller out of WSGITestCase.

bea/c283cb: move 'wishlist' severity from bug summary to .severity attribute.

command:serve-storage: rename server_version to BE-storage-server/<VERSION>.

This catches the server version up with:

  commit 0336db8d4052a319f1d959a33fc847814551e3f8
  Author: W. Trevor King <wking@tremily.us>
  Date:   Wed Aug 29 23:55:37 2012 -0400

    command:serve-storage: rename `be serve` -> `be serve-storage`.

command:serve_commands: allow unspecified parameters (use defaults).

Also raise UnknownCommand if there is no `command` key in the posted
dict (malformed request).

With the new code, you can run commands with:

  $ wget --post-data='command: list' http://localhost:8000/run/

instead of having to go through and specify all the parameters
explicitly.  This will make the command server more robust for use
with older clients (who may not know about all the parameters that the
server knows about).  Parameters sent by the client that the server
does not know about are silently ignored.

util:wsgi: add HandlerErrorApp to return HTTP errors.

util:wsgi: fix WSGI_AppObject.default_callback -> .default_handler typo.

bea/c283cb: remove Be-devel footer from Holger (Timmie)'s comment.

bea/c283cb: merge earlier hosting-integration emails onto gitorious-issues bug.

command:import_xml: fix `--r` -> `-r` in long help.

command:import_xml: fix be-mbox-to-xml -> be-mail-to-xml.

This catches the doc up with misc/xml/be-mail-to-xml:

  commit c8985785eb741ff646082879f1ca5e9cfe3873b0
  Author: W. Trevor King <wking@drexel.edu>
  Date:   Wed Jan 20 15:22:28 2010 -0500

    'be-mbox-to-xml' -> 'be-mail-to-xml' + support for several formats.

bea/c283cb: merge Praveen's gitorious-issues integration request.

This was merge request #11 on gitorious.

misc:completion:be.bash: use tabs to indent shell script.

misc:completion: rename _be to be.zsh for consistency with be.bash.

misc:completion: merge zsh completion from Markus Vock.

This was merge request #9 on gitorious.

doc:install: we only use CherryPy for HTTPS.

We use wsgiref.simple_server for HTTP.

doc:tutorial: document `be serve-storage`.

command:serve-storage: rename `be serve` -> `be serve-storage`.

This will help avoid confusion between

  be serve-storage

and

  be serve-commands

Rewrite commands to use bugdirs instead of a single bugdir.

The bulk of the work is in regard to XML, with new BugDir.xml and
.from_xml methods to support the new <bugdir> entity.  I also split
the guts import_xml's ._run method into sub-methods to make the import
logic more obvious.

util:wsgi: add BEExceptionApp for translating storage exceptions.

This fixes .test_get_initial_value for the HTTP backend, because the
tests use TestingHTTP.getURL, which only catch HandlerError, not the
more specific storage exceptions.

bugdir: add `update` argument to BugDir.append().

This avoids a deepcopy error where the BugDir tries to update before
the Bug has had it's uuid assigned:

  Traceback (most recent call last):
    ...
    File ".../libbe/command/merge.py", line 168, in _run
      newCommTree = copy.deepcopy(bugB.comment_root)
    File "/usr/lib64/python2.7/copy.py", line 190, in deepcopy
      y = _reconstruct(x, rv, 1, memo)
    ...
    File "/usr/lib64/python2.7/copy.py", line 352, in _reconstruct
      y.append(item)
    File ".../libbe/bugdir.py", line 263, in append
      self._bug_map_gen()
    File ".../libbe/bugdir.py", line 152, in _bug_map_gen
      map[bug.uuid] = bug
  AttributeError: 'Bug' object has no attribute 'uuid'

bugdir: add BugDir.xml(), .from_xml(), and .append().

bug: fix invalid root element comment -> bug in Bug.from_xml().

bug: fix leading comment indentation in Bug.xml().

bug: add doctest for Bug.xml().

Allow symlinks in bugdir directories.

This allows you to do things like:

  $ mkdir -p /tmp/joint-repo/.be
  $ cd /tml/joint-repo/.be
  $ ln -s ~/src/be/.be/version
  $ ln -s ~/src/be/.be/bea86499-824e-4e77-b085-2d581fa9ccab/
  $ ln -s ~/src/BEurtle/.be/7017b289-f207-4e39-9746-f58323404eba/
  $ be list

without crashing with a:

  Traceback (most recent call last):
    File ".../libbe/storage/base.py", line 316, in children
      return self._children(*args, **kwargs)
    File ".../libbe/storage/vcs/base.py", line 820, in _children
      path = self.path(id, revision, relpath=False)
    File ".../libbe/storage/vcs/base.py", line 721, in path
      path = self._cached_path_id.path(id)
    File ".../libbe/storage/vcs/base.py", line 280, in path
      raise InvalidID(uuid)
  libbe.storage.base.InvalidID: 7017b289-f207-4e39-9746-f58323404eba in revision None

Currently it only lists the first bug directory it comes across, but
after this patch, it doesn't crash ;).

util:plugin: modnames() should only list *.py or *.pyc files.

By appending '.py' to *everything*, it was listing '__pycache__' for
Python 3.

gitignore: ignore autogenerated dist/.

gitignore: ignore autogenerated doc/libbe/.

libbe:util:wsgi: extract WSGI utilities into a separate module.

Convert my subscription email to tremily.

command:serve_commands: remove duplicate cruft and get working unit tests.

command:serve: add ability to pass raw POST data with getURL.

This is analagous to the earlier change to get_post_url:

  commit 0cd072b9710ee964e6f449abd9265d85e02f34d2
  Author: W. Trevor King <wking@tremily.us>
  Date:   Fri Aug 24 09:29:58 2012 -0400

    util:http: add ability to pass raw POST data with get_post_url.

command:serve_commands: new command for running a command server.

This is an initial step towards improving BE's efficiency.

Previously, BE gets slow as the bug count increases for several
commands (e.g. `be list`), because it takes time to load the bugdir
information from disk at each invocation.  If you use a remote repo
(`be --repo http://localhost:8000/ list`), the server process may have
already loaded the repo from disk, but now your listing process has to
fetch everything over the wire.  This is even worse than loading it
from disk.

With the new `be serve-commands` and `be --server URL ...` pair, the
bugdir loading happens once on the server, and all the processing is
also carried out on the server.  This means that calls like `be
--server http://localhost:8000/ list` will scale much better than
other methods.  For example:

  $ time be --server http://localhost:8000/ list > /dev/null

  real    0m2.234s
  user    0m0.548s
  sys     0m0.114s
  $ time be --server http://localhost:8000/ list > /dev/null

  real    0m0.730s
  user    0m0.548s
  sys     0m0.112s
  $ time be list > /dev/null

  real    0m2.453s
  user    0m2.289s
  sys     0m0.166s
  $ time be list > /dev/null

  real    0m2.521s
  user    0m2.350s
  sys     0m0.172s

The first call to a cold server takes about the same time as a local
call, because you need to load the bugs from the filesystem.  However,
later calls to a warm server are 3x faster, while later local calls
are still slow.

This is currently a minimal working implementation.  There's a good
deal of code in libbe.command.serve that I'd like to abstract out into
a libbe.util library (since there's still a bunch of duplication
between libbe.command.serve and libbe.command.serve_commands).  The
remote calls are also not as fast as I'd like, likely due to library
load times.  This commit just locks in an initial working
implementation.

command:base: only cleanup UseInterface.storage_callback if it's there.

It's hard to see why it wouldn't be, but .setup_command handles the
case where it's missing, so we should be consistent here.

command:base: use is/is-not None instead of ==/!= None in setup_command.

More Pythonic.

command:serve: wrap server in ExceptionApp regardless of SSL.

Previously, only the SSL server was using ExceptionApp.

util:http: add ability to pass raw POST data with get_post_url.

util:http: convert urllib2.URLError into HTTPError in get_post_url.

Also rework liburl2.HTTPError handling to get both the reason and the
error code into the HTTPError message.

util:http: pull HTTP helpers from libbe.storage.http into their own module.

This way they can be shared with the upcoming Command._run_remote.