From b5cbf7b2ac05efcfd40e6d791f13ceda459536b3 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Mon, 3 Sep 2012 15:15:38 -0400 Subject: [PATCH] command:help: add `repo` and `server` topics. --- libbe/command/help.py | 61 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) 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 -- 2.26.2