severely lacking documentation + missing dependencies in ubuntu pacakge

[bob smith]

Two *critical* pieces of information are lacking, resulting in 3 lost hours that I'll never get back... hopefully it'll help someone else.

Both of these items result in the dreaded "404 The resource could not be found" which seems to date back many years.

1.
If the python package "PasteDeploy" is not installed, "--prefix" is SILENTLY IGNORED in "serve-branches".
That is because in ./loggerhead/main.py:132 you fall back to skipping the prefix middleware, WITHOUT WARNING.

It doesn't matter that you mention it in passing in your documentation.
It doesn't matter that the ubuntu pacakge *suggests* the 'python-pastedeploy' package.

What matters is: When a poor unsuspecting user does 'apt-get install loggerhead',
then creates "/etc/serve-branches.conf" based on *your example* which has "prefix",
and runs "service start loggerhead" - it won't work.

It also won't work without ANY warning/logging when running from the command line.

2.
When trying to serve multiple repositories,
Without adding "--allow-writes", the 'serve-branches' adds some "readonly+" nonsense, again resulting in cryptic and unexplained "404 the resource could not be found" error.
The only way to even discover it is to resort to 'strace' - because useful logging is non-existing.

To demonstrate:

Start the program:

    strace -f -e open serve-branches --port=9999 /srv/bzr

From another terminal, try to access an existing bzr repo:

    curl http://127.0.0.1:9999/foobar

The resulting access is:

    [pid 4802] open("/home/ubuntu/readonly+/srv/bzr/.bzr/branch-format", O_RDONLY) = -1 ENOENT (No such file or directory)

And only if started with "--allow-writes", then directory is correct:

    [pid 5311] open("/srv/bzr/foobar/.bzr/branch-format", O_RDONLY) = 6

Perhaps this makes perfect sense to you, as you are experienced with bzr/loggerhead.
For for a new user - this is completely obscure as it is NEVER clear why "--allow-writes" should affect such a thing.

BTW,
I see a "NEWS" entry about "allow-writes" bugfix for 1.17, but this issue still happens with 1.19~bzr479-3 from Ubuntu 14.04.