aboutsummaryrefslogtreecommitdiffstats
path: root/libbe
diff options
context:
space:
mode:
authorW. Trevor King <wking@tremily.us>2012-09-03 15:15:38 -0400
committerW. Trevor King <wking@tremily.us>2012-09-03 15:15:38 -0400
commitb5cbf7b2ac05efcfd40e6d791f13ceda459536b3 (patch)
tree75c2bd0adbbf31d2f84f35ae8b38a184a2f4b1fc /libbe
parent9bf572f523430225e268095b9c653dee9c37c803 (diff)
downloadbugseverywhere-b5cbf7b2ac05efcfd40e6d791f13ceda459536b3.tar.gz
command:help: add `repo` and `server` topics.
Diffstat (limited to 'libbe')
-rw-r--r--libbe/command/help.py61
1 files changed, 60 insertions, 1 deletions
diff --git a/libbe/command/help.py b/libbe/command/help.py
index 869a35a..e655105 100644
--- a/libbe/command/help.py
+++ b/libbe/command/help.py
@@ -24,7 +24,66 @@ import libbe
import libbe.command
import libbe.command.util
-TOPICS = {}
+
+TOPICS = {
+ 'repo': """A BE repository containing child bugdirs
+
+BE repositories are stored in an abstract `Storage` instance, which
+may or may not be versioned. If you're using BE to track bugs in your
+local software, you'll probably be using an on-disk storage based on
+the VCS you use to version the storage. See `be help init` for
+details about automatic VCS-detection.
+
+While most users will be using local storage, BE also supports remote
+storage servers. This allows projects to publish their local
+repository in a way that's directly accessible to remote users. The
+remote users can then use a local BE client to interact with the
+remote repository, without having to create a local copy of the
+repository. The remote server will be running something like:
+
+ $ be serve-storage --host 123.123.123.123 --port 54321
+
+And the local client can run:
+
+ $ be --repo http://123.123.123.123:54321 list
+
+or whichever command they like.
+
+Because the storage server serves repositories at the `Storage` level,
+it can be inefficient. For example, `be list` will have to transfer
+the data for all the bugs in a repository over the wire. The storage
+server can also be harder to lock down, because users with write
+access can potentially store data that cannot be parsed by BE. For a
+more efficient server, see `be serve-commands`.
+""",
+##
+ 'server': """A server for remote BE command execution
+
+The usual way for a user to interact with a BE bug tracker for a
+particular project is to clone the project repository. They can then
+use their local BE client to browse the repository and make changes,
+before pushing their changes back upstream. For the average user
+seeking to file a bug or comment, this can be too much work. One way
+to simplify the process is to use a storage server (see `be help
+repo`), but this is not always ideal. A more robust approach is to
+use a command server.
+
+The remote server will be running something like:
+
+ $ be serve-commands --host 123.123.123.123 --port 54321
+
+And the local client can run:
+
+ $ be --server http://123.123.123.123:54321 list
+
+or whichever command they like. The command line arguments are parsed
+locally, and then POSTed to the command server, where the command is
+executed. The output of the command is returned to the client for
+display. This requires much less traffic over the wire than running
+the same command via a storage server.
+""",
+ }
+
class Help (libbe.command.Command):
"""Print help for given command or topic