diff options
| author | W. Trevor King <wking@drexel.edu> | 2010-01-24 11:22:53 -0500 |
|---|---|---|
| committer | W. Trevor King <wking@drexel.edu> | 2010-01-24 11:22:53 -0500 |
| commit | 9e566087db878ee9420faaa422e5e3ea9bce724e (patch) | |
| tree | 19fcc72835c749f5bc607fe5aac9e76e54794b82 | |
| parent | 4ea7a28e1bd97df5997b5f884378bd7d64edff6e (diff) | |
| parent | 53074356bf715c820d3b9b852cd45e5073ba765d (diff) | |
| download | bugseverywhere-9e566087db878ee9420faaa422e5e3ea9bce724e.tar.gz | |
Merged be.doc documentation rewrite + bugfixes + new bugs
Highlights:
* Fix broken Diff.comment_body_change_string implementation.
* Fix List --severity handling, added --important
* Fix `be target --help`
* Fix non-text/plain `be comment` code and added 'Created
comment...' output
27 files changed, 700 insertions, 105 deletions
diff --git a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/52034fd0-ec50-424d-b25d-2beaf2d2c317/comments/79fb6ef2-176c-45c0-b898-59c3c3e0aafe/body b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/52034fd0-ec50-424d-b25d-2beaf2d2c317/comments/79fb6ef2-176c-45c0-b898-59c3c3e0aafe/body index 7dbeebb..3ed77e7 100644 --- a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/52034fd0-ec50-424d-b25d-2beaf2d2c317/comments/79fb6ef2-176c-45c0-b898-59c3c3e0aafe/body +++ b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/52034fd0-ec50-424d-b25d-2beaf2d2c317/comments/79fb6ef2-176c-45c0-b898-59c3c3e0aafe/body @@ -5,7 +5,7 @@ > and commit only those files. This is doable, but maybe not worth > the trouble. -On the other hand, just attemting to commit evverything after each +On the other hand, just attemting to commit everything after each command would make it nice and easy to commit bug fixes: be --auto-commit status XYZ fixed which would commit whatever changes you had outstanding with an diff --git a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/52034fd0-ec50-424d-b25d-2beaf2d2c317/values b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/52034fd0-ec50-424d-b25d-2beaf2d2c317/values index d060e87..5b332ed 100644 --- a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/52034fd0-ec50-424d-b25d-2beaf2d2c317/values +++ b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/52034fd0-ec50-424d-b25d-2beaf2d2c317/values @@ -1,6 +1,10 @@ creator: W. Trevor King <wking@drexel.edu> +extra_strings: +- BLOCKED-BY:5fb11e65-68a0-4015-b404-737238299cdc + + reporter: Martin F Krafft <madduck@debian.org> diff --git a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/5fb11e65-68a0-4015-b404-737238299cdc/comments/f3e90a7e-b8c4-4a7c-8609-6a783ae59762/body b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/5fb11e65-68a0-4015-b404-737238299cdc/comments/f3e90a7e-b8c4-4a7c-8609-6a783ae59762/body new file mode 100644 index 0000000..80133bf --- /dev/null +++ b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/5fb11e65-68a0-4015-b404-737238299cdc/comments/f3e90a7e-b8c4-4a7c-8609-6a783ae59762/body @@ -0,0 +1,18 @@ +Provide hooks so users can easily setup auto-commits, subscriber +notification, etc. Probably either Darcs-style options: + $ be COMMAND --help + ... + --posthook=COMMAND Specify command to run after this command. + --no-posthook Do not run posthook command. + --prompt-posthook Prompt before running posthook. [DEFAULT] + --run-posthook Run posthook command without prompting. + ... +or a Git-style hooks directory: + $ tree .be + .be/ + |-- version + |-- hooks + . |-- post-commit.sh + . |-- pre-commit.sh + `-- update.sh + diff --git a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/5fb11e65-68a0-4015-b404-737238299cdc/comments/f3e90a7e-b8c4-4a7c-8609-6a783ae59762/values b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/5fb11e65-68a0-4015-b404-737238299cdc/comments/f3e90a7e-b8c4-4a7c-8609-6a783ae59762/values new file mode 100644 index 0000000..4cd8b7a --- /dev/null +++ b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/5fb11e65-68a0-4015-b404-737238299cdc/comments/f3e90a7e-b8c4-4a7c-8609-6a783ae59762/values @@ -0,0 +1,8 @@ +Author: W. Trevor King <wking@drexel.edu> + + +Content-type: text/plain + + +Date: Sat, 23 Jan 2010 19:17:10 +0000 + diff --git a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/5fb11e65-68a0-4015-b404-737238299cdc/values b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/5fb11e65-68a0-4015-b404-737238299cdc/values new file mode 100644 index 0000000..3e88ad1 --- /dev/null +++ b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/5fb11e65-68a0-4015-b404-737238299cdc/values @@ -0,0 +1,21 @@ +creator: W. Trevor King <wking@drexel.edu> + + +extra_strings: +- BLOCKS:52034fd0-ec50-424d-b25d-2beaf2d2c317 + + +reporter: W. Trevor King <wking@drexel.edu> + + +severity: minor + + +status: open + + +summary: Add change hooks to Storage class + + +time: Sat, 23 Jan 2010 19:08:40 +0000 + diff --git a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/7cb42a60-c977-40db-b2a1-19917c10cace/comments/a555d577-7f8c-49f2-96f6-263ce5fdff8e/body b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/7cb42a60-c977-40db-b2a1-19917c10cace/comments/a555d577-7f8c-49f2-96f6-263ce5fdff8e/body new file mode 100644 index 0000000..c45d2c7 --- /dev/null +++ b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/7cb42a60-c977-40db-b2a1-19917c10cace/comments/a555d577-7f8c-49f2-96f6-263ce5fdff8e/body @@ -0,0 +1,23 @@ +Usage case: + * User A installs version 1.0 which contains bug /abc. + * Development continues, fixing bug /abc. + * User A wants to see which bugs affect their version, and query the + main bug repository. + $ be --repo http://bugseverywhere.org/bugs list --this-version + bea/abc:om: Whatsit not implemented. + $ be --repo http://bugseverywhere.org/bugs show bea/abc + ID : abc... + Short name : bea/abc + Severity : minor + Status : fixed + ... + Whatsit not implemented. + --------- Comment --------- + Name: bea/abc/def + From: ... + Date: Sat, 23 Jan 2010 14:00 ... + + Whatsit implemented. + "Aha!", says the user, "I need to upgrade to a version of BE + that's more recent than 2010/01/23 to get Whatsit functionality." + diff --git a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/7cb42a60-c977-40db-b2a1-19917c10cace/comments/a555d577-7f8c-49f2-96f6-263ce5fdff8e/values b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/7cb42a60-c977-40db-b2a1-19917c10cace/comments/a555d577-7f8c-49f2-96f6-263ce5fdff8e/values new file mode 100644 index 0000000..3b8ba33 --- /dev/null +++ b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/7cb42a60-c977-40db-b2a1-19917c10cace/comments/a555d577-7f8c-49f2-96f6-263ce5fdff8e/values @@ -0,0 +1,8 @@ +Author: W. Trevor King <wking@drexel.edu> + + +Content-type: text/plain + + +Date: Sat, 23 Jan 2010 18:59:03 +0000 + diff --git a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/7cb42a60-c977-40db-b2a1-19917c10cace/values b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/7cb42a60-c977-40db-b2a1-19917c10cace/values new file mode 100644 index 0000000..cb9a372 --- /dev/null +++ b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/bugs/7cb42a60-c977-40db-b2a1-19917c10cace/values @@ -0,0 +1,17 @@ +creator: W. Trevor King <wking@drexel.edu> + + +reporter: W. Trevor King <wking@drexel.edu> + + +severity: minor + + +status: open + + +summary: '`be list --this-version` listing bugs affecting your version of BE' + + +time: Sat, 23 Jan 2010 18:49:03 +0000 + diff --git a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/settings b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/settings index b3c2b81..8ecc0cd 100644 --- a/.be/bea86499-824e-4e77-b085-2d581fa9ccab/settings +++ b/.be/bea86499-824e-4e77-b085-2d581fa9ccab/settings @@ -1,6 +1,3 @@ -encoding: utf-8 - - extra_strings: - "SUBSCRIBE:W. Trevor King <wking@drexel.edu>\tall\t*" @@ -15,6 +12,3 @@ inactive_status: - - disabled - Unknown meaning. For backwards compatibility with old BE bugs. - -vcs_name: bzr - @@ -27,7 +27,7 @@ SHELL = /bin/bash PATH = /usr/bin:/bin # Directories with semantic meaning -DOC_DIR := doc +DOC_DIR := doc/src # Variables that will be extended by module include files GENERATED_FILES := libbe/_version.py build @@ -1,5 +1,6 @@ January 23, 2010 - * Added `be list --mine`, listing bugs belonging to you. + * Added 'Created comment with ID .../.../...' output to `be comment`. + * Added --important and --mine to `be list`. January 20, 2010 * Renamed 'be-mbox-to-xml' -> 'be-mail-to-xml' and added support for @@ -6,7 +6,7 @@ moment, but is easily extensible. It can also function with no RCS at all. The idea is to package the bug information with the source code, so that -bugs can be marked 'fixed' in the branches that fix them. So, instead of +bugs can be marked "fixed" in the branches that fix them. So, instead of numbers, bugs have globally unique ids. @@ -17,7 +17,24 @@ set the bug root to your project root, so that Bugs Everywhere works in any part of your project tree. $ be init -r $PROJECT_ROOT -To create bugs, use "be new $DESCRIPTION". To comment on bugs, you -can can use "be comment $BUG_ID". To close a bug, use "be close -$BUG_ID" or "be status $BUG_ID fixed". For more commands, see "be -help". You can also look at the usage examples in test_usage.sh. +To create bugs, use ``be new $DESCRIPTION``. To comment on bugs, you +can can use ``be comment $BUG_ID``. To close a bug, use +``be close $BUG_ID`` or ``be status $BUG_ID fixed``. For more +commands, see ``be help``. You can also look at the usage examples in +``test_usage.sh``. + +Documentation +============= + +If ``be help`` isn't scratching your itch, there's also + +* doc/tutorial (a gentle introduction to BE) +* doc/distributed_bugtracking (notes on distributed workflows) +* doc/spam (notes on removing spam entries from VCSs) +* doc/README.dev (a guide to hacking BE) + +The documentation is marked up in reStructuredText_, so you can use +the docutils_ to convert it to other formats if you desire. + +.. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html +.. _docutils: http://docutils.sourceforge.net/ diff --git a/doc/README.dev b/doc/README.dev index a2b8d30..cfb1896 100644 --- a/doc/README.dev +++ b/doc/README.dev @@ -4,61 +4,68 @@ 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. +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. +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 +any of your completable ``Argument()`` instances (in your command's +``.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. +``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... +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 +Run any tests in your module with:: -For a definition of "any tests", see test.py's add_module_tests() -function. + 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). +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:: - $ python -m cProfile -o profile be [command] [args] - $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)" + import sys, traceback + print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:]) -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. +into expensive functions (e.g. ``libbe.util.subproc.invoke()``) if +you're not sure why they're being called. diff --git a/doc/be.1.sgml b/doc/src/be.1.sgml index a2df21f..a2df21f 100644 --- a/doc/be.1.sgml +++ b/doc/src/be.1.sgml diff --git a/doc/module.mk b/doc/src/module.mk index 960f7c0..ea4eacc 100644 --- a/doc/module.mk +++ b/doc/src/module.mk @@ -23,7 +23,7 @@ # Makefile module for documentation -MODULE_DIR := doc +MODULE_DIR := doc/src MANPAGES = be.1 manpage_files = $(patsubst %,${MODULE_DIR}/%,${MANPAGES}) diff --git a/doc/tutorial b/doc/tutorial new file mode 100644 index 0000000..5a91bcd --- /dev/null +++ b/doc/tutorial @@ -0,0 +1,442 @@ +Tutorial +======== + +Introduction +------------ + +Bugs Everywhere (BE) is a bugtracker built on distributed revision +control. The idea is to package the bug information with the source +code, so that developers working on the code can make appropriate +changes to the bug repository as they go. For example, by marking a +bug as "fixed" and applying the fixing changes in the same commit. +This makes it easy to see what's been going on in a particular branch +and helps keep the bug repository in sync with the code. + +However, there are some differences compared to centralized +bugtrackers. Because bugs and comments can be created by several +users in parallel, they have globally unique IDs_ rather than numbers. +There is also a developer-friendly command-line_ interface to +compliment the user-friendly web_ and email_ interfaces. This +tutorial will focus on the command-line interface as the most +powerful, and leave the web and email interfaces to other documents. + +.. _command-line: `Command-line interface`_ +.. _web: ../doc/tutorial-html +.. _email: ../doc/tutorial-email + +Installation +------------ + +If your distribution packages BE, it will be easiest to use their package. +For example, most Debian-based distributions support:: + + $ apt-get install bugs-everywhere + +Bugs +---- + +If you have any problems with BE, you can look for matching bugs:: + + $ be --repo http://bugseverywhere.org/bugs list + +If your bug isn't listed, please open a new bug:: + + $ be --repo http://bugseverywhere.org/bugs new 'bug' + Created bug with ID bea/abc + $ be --repo http://bugseverywhere.org/bugs comment bea/def + <editor spawned for comments> + + +Command-line interface +---------------------- + +Help +~~~~ + +All of the following information elaborates on the command help text, +which is stored in the code itself, and therefore more likely to be up +to date. You can get a list of commands and topics with:: + + $ be help + +Or see specific help on ``COMMAND`` with + + $ be help COMMAND + +for example:: + + $ be help init + +will give help on the ``init`` command. + +Initialization +~~~~~~~~~~~~~~ + +You're happily coding in your Arch_ / Bazaar_ / Darcs_ / Git_ / +Mercurial_ versioned project and you discover a bug. "Hmm, I'll need +a simple way to track these things", you think. This is where BE +comes in. One of the benefits of distributed versioning systems is +the ease of repository creation, and BE follows this trend. Just +type:: + + $ be init + Using <VCS> for revision control. + BE repository initialized. + +in your project's root directory. This will create a ``.be`` +directory containing the bug repository and notify your VCS so it will +be versioned starting with your next commit. See:: + + $ be help init + +for specific details about where the ``.be`` directory will end up +if you call it from a directory besides your project's root. + +.. _Arch: http://www.gnu.org/software/gnu-arch/ +.. _Bazaar: http://bazaar.canonical.com/ +.. _Darcs: http://darcs.net/ +.. _Git: http://git-scm.com/ +.. _Mercurial: http://mercurial.selenic.com/ + +Inside the ``.be`` directory (among other things) there will be a long +UUID_ directory. This is your bug directory. The idea is that you +could keep several bug directories in the same repository, using one +to track bugs, another to track roadmap issues, etc. See IDs_ for +details. For BE itself, the bug directory is +``bea86499-824e-4e77-b085-2d581fa9ccab``, which is why all the bug and +comment IDs in this tutorial will start with ``bea/``. + +.. _UUID: http://en.wikipedia.org/wiki/Universally_Unique_Identifier + + +Creating bugs +~~~~~~~~~~~~~ + +Create new bugs with:: + + $ be new <SUMMARY> + +For example:: + + $ be new 'Missing demuxalizer functionality' + Created bug with ID bea/28f + +If you are entering a bug reported by another person, take advantage +of the ``--reporter`` option to give them credit:: + + $ be new --reporter 'John Doe <jdoe@example.com>' 'Missing whatsit...' + Created bug with ID bea/81a + +See ``be help new`` for more details. + +While the bug summary should include the appropriate keywords, it +should also be brief. You should probably add a comment immediately +giving a more elaborate explanation of the problem so that the +developer understands what you want and when the bug can be considered +fixed. + +Commenting on bugs +~~~~~~~~~~~~~~~~~~ + +Bugs are like little mailing lists, and you can comment on the bug +itself or previous comments, attach files, etc. For example + + $ be comment abc/28f "Thoughts about demuxalizers..." + Created comment with ID abc/28f/97a + $ be comment abc/def/012 "Oops, I forgot to mention..." + Created comment with ID abc/28f/e88 + +Usually comments will be long enough that you'll want to compose them +in a text editor, not on the command line itself. Running ``be +comment`` without providing a ``COMMENT`` argument will try to spawn +an editor automatically (using your environment's ``VISUAL`` or +``EDITOR``, see `Guide to Unix, Environmental Variables`_). + +.. _Guide to Unix, Environmental Variables: + http://en.wikibooks.org/wiki/Guide_to_Unix/Environment_Variables + +You can also pipe the comment body in on stdin, which is especially +useful for binary attachments, etc.:: + + $ cat screenshot.png | be comment --content-type image/png bea/28f + Created comment with ID bea/28f/35d + +It's polite to insert binary attachments under comments that explain +the content and why you're attaching it, so the above should have been + + $ be comment bea/28f "Whosit dissapears when you mouse-over whatsit." + Created comment with ID bea/28f/41d + $ cat screenshot.png | be comment --content-type image/png bea/28f/41d + Created comment with ID bea/28f/35d + +For more details, see ``be help comment``. + +Showing bugs +~~~~~~~~~~~~ + +Ok, you understand how to enter bugs, but how do you get that +information back out? If you know the ID of the item you're +interested in (e.g. bug bea/28f), try:: + + $ be show bea/28f + ID : 28fb711c-5124-4128-88fe-a88a995fc519 + Short name : bea/28f + Severity : minor + Status : open + Assigned : + Reporter : + Creator : ... + Created : ... + Missing demuxalizer functionality + --------- Comment --------- + Name: bea/28f/97a + From: ... + Date: ... + + Thoughts about demuxalizers... + --------- Comment --------- + Name: bea/28f/e88 + From: ... + Date: ... + + Thoughts about demuxalizers... + --------- Comment --------- + Name: bea/28f/41d + From: ... + Date: ... + + Whosit dissapears when you mouse-over whatsit. + --------- Comment --------- + Name: bea/28f/35d + From: ... + Date: ... + + Content type image/png not printable. Try XML output instead + +You can also get a single comment body, which is useful for extracting +binary attachments:: + + $ be show --only-raw-body bea/28f/35d > screenshot.png + +There is also an XML output format, which can be useful for emailing +entries around, scripting BE, etc. + + $ be show --xml bea/35d + <?xml version="1.0" encoding="UTF-8" ?> + <be-xml> + ... + +Listing bugs +~~~~~~~~~~~~ + +If you *don't* know which bug you're interested in, you can query +the whole bug directory:: + + $ be list + bea/28f:om: Missing demuxalizer functionality + bea/81a:om: Missing whatsit... + +There are a whole slew of options for filtering the list of bugs. See +``be help list`` for details. + +Showing changes +~~~~~~~~~~~~~~~ + +Often you will want to see what's going on in another dev's branch or +remind yourself what you've been working on recently. All VCSs have +some sort of ``diff`` command that shows what's changed since revision +``XYZ``. BE has it's own command that formats the bug-repository +portion of those changes in an easy-to-understand summary format. To +compare your working tree with the last commit:: + + $ be diff + New bugs: + bea/01c:om: Need command output abstraction for flexible UIs + Modified bugs: + bea/343:om: Attach tests to bugs + Changed bug settings: + creator: None -> W. Trevor King <wking@drexel.edu> + +Compare with a previous revision ``480``:: + + $ be diff 480 + ... + +Compare your BE branch with the trunk:: + + $ be diff --repo http://bugseverywhere.org/bugs/ + +Manipulating bugs +~~~~~~~~~~~~~~~~~ + +There are several commands that allow to to set bug properties. They +are all fairly straightforward, so we will merely point them out here, +and refer you to ``be help COMMAND`` for more details. + +* ``assign``, Assign an individual or group to fix a bug +* ``depend``, Add/remove bug dependencies +* ``due``, Set bug due dates +* ``status``, Change a bug's status level +* ``severity``, Change a bug's severity level +* ``tag``, Tag a bug, or search bugs for tags +* ``target``, Assorted bug target manipulations and queries + +You can also remove bugs you feel are no longer useful with +``be remove``, and merge duplicate bugs with ``be merge``. + +Subscriptions +~~~~~~~~~~~~~ + +Since BE bugs act as mini mailing lists, we provide ``be subscribe`` +as a way to manage change notification. You can subscribe to all +the changes with:: + + $ be subscribe --types all DIR + +Subscribe only to bug creaton on bugseverywhere.org with:: + + $ be subscribe --server bugseverywhere.org --types new DIR + +Subscribe to get all the details about bug ``bea/28f``:: + + $ be subscribe --types new bea/28f + +To unsubscribe, simply repeat the subscription command adding the +``--unsubscribe`` option, but be aware that it may take some time for +these changes to propogate between distributed repositories. If you +don't feel confident in your ability to filter email, it's best to +only subscribe to the repository for which you have direct write +access. + +Managing bug directories +~~~~~~~~~~~~~~~~~~~~~~~~ + +``be set`` lets you configure a bug directory. You can set + +* ``active_status`` + The allowed active bug states and their descriptions. +* ``inactive_status`` + The allowed inactive bug states and their descriptions. +* ``severities`` + The allowed bug severities and their descriptions. +* ``target`` + The current project development target (bug UUID). +* ``extra_strings`` + Space for an array of extra strings. You usually won't bother with + this directly. + +For example, to set the current target to '1.2.3':: + + $ be set target $(be target --resolve '1.2.3') + +Import XML +~~~~~~~~~~ + +For serializing bug information (e.g. to email to a mailing list), use:: + + $ be show --xml bea/28f > bug.xml + +This information can be imported into (another) bug directory via + + $ be import-xml bug.xml + +Also distributed with BE are some utilities to convert mailboxes +into BE-XML (``be-mail-to-xml``) and convert BE-XML into mbox_ +format for reading in your mail client. + +.. _mbox: http://en.wikipedia.org/wiki/Mbox + +Export HTML +~~~~~~~~~~~ + +To create a static dump of your bug directory, use:: + + $ be html + +This is a fairly flexible command, see ``be help html`` for details. +It works pretty well as the browsable part of a public interface using +the email_ interface for interactive access. + +BE over HTTP +~~~~~~~~~~~~ + +Besides using BE to work directly with local VCS-based repositories, +you can use:: + + $ be serve + +To serve a repository over HTTP. For example:: + + $ be serve > server.log 2>&1 & + $ be --repo http://localhost:8000 list + +Of course, be careful about serving over insecure networks, since +malicous users could fill your disk with endless bugs, etc. You can +dissable write access by using the ``--read-only`` option, which would +make serving on a public network safer. + +Driving the VCS through BE +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since BE uses internal storage drivers for its various backends, it +seemed useful to provide a uniform interface to some of the common +functionality. These commands are not intended to replace the usually +much more powerful native VCS commands, but to provide an easy means +of simple VCS-agnostic scripting for BE user interfaces, etc. + +Currently, we only expose ``be commit``, which commits all currently +pending changes. + + +IDs +--- + +Format +~~~~~~ + +BE IDs are formatted:: + + <bug-directory>[/<bug>[/<comment>]] + +where each ``<..>`` is a UUID. For example:: + + bea86499-824e-4e77-b085-2d581fa9ccab/3438b72c-6244-4f1d-8722-8c8d41484e35 + +refers to bug ``3438b72c-6244-4f1d-8722-8c8d41484e35`` which is +located in bug directory ``bea86499-824e-4e77-b085-2d581fa9ccab``. +This is a bit of a mouthful, so you can truncate each UUID so long as +it remains unique. For example:: + + bea/343 + +If there were two bugs ``3438...`` and ``343a...`` in ``bea``, you'd +have to use:: + + bea/3438 + +BE will only truncate each UUID down to three characters to slightly +future-proof the short user ids. However, if you want to save keystrokes +and you *know* there is only one bug directory, feel free to truncate +all the way to zero characters:: + + /3438 + +Cross references +~~~~~~~~~~~~~~~~ + +To refer to other bug-directories/bugs/comments from bug comments, simply +enclose the ID in pound signs (``#``). BE will automatically expand the +truncations to the full UUIDs before storing the comment, and the reference +will be appropriately truncated (and hyperlinked, if possible) when the +comment is displayed. + +Scope +~~~~~ + +Although bug and comment IDs always appear in compound references, +UUIDs at each level are globally unique. For example, comment +``bea/343/ba96f1c0-ba48-4df8-aaf0-4e3a3144fc46`` will *only* appear +under ``bea/343``. The prefix (``bea/343``) allows BE to reduce +caching global comment-lookup tables and enables easy error messages +("I couldn't find ``bea/343/ba9`` because I don't know where the +``bea`` bug directory is located"). diff --git a/doc/tutorial-email b/doc/tutorial-email new file mode 120000 index 0000000..b25875f --- /dev/null +++ b/doc/tutorial-email @@ -0,0 +1 @@ +../interfaces/email/interactive/README
\ No newline at end of file diff --git a/doc/tutorial-html b/doc/tutorial-html new file mode 100644 index 0000000..0822ebd --- /dev/null +++ b/doc/tutorial-html @@ -0,0 +1,3 @@ +There's an interactive HTML interface in the works +(http://bitbucket.org/sjl/cherryflavoredbugseverywhere/), but it's not +ready for use as a public interface yet. diff --git a/interfaces/email/interactive/README b/interfaces/email/interactive/README index b25054c..f7d57ad 100644 --- a/interfaces/email/interactive/README +++ b/interfaces/email/interactive/README @@ -2,15 +2,14 @@ Overview ======== The interactive email interface to Bugs Everywhere (BE) attempts to -provide a Debian-bug-tracking-system-style interface to a BE +provide a `Debian-bug-tracking-system-style`_ interface to a BE repository. Users can mail in bug reports, comments, or control requests, which will be committed to the served repository. Developers can then pull the changes they approve of from the served repository into their other repositories and push updates back onto the served repository. -For details about the Debian bug tracking system that inspired this -interface, see http://www.debian.org/Bugs . +.. _Debian-bug-tracking-system-style: http://www.debian.org/Bugs Architecture ============ @@ -18,27 +17,34 @@ Architecture In order to reduce setup costs, the entire interface can piggyback on an existing email address, although from a security standpoint it's probably best to create a dedicated user. Incoming email is filtered -by procmail, with matching emails being piped into be-handle-mail for -execution. - -Once be-handle-mail receives the email, the parsing method is selected -according to the subject tag that procmail used grab the email in the -first place. There are four parsing styles: - Style Subject - creating bugs [be-bug:submit] new bug summary - commenting on bugs [be-bug:<bug-id>] commit message - control [be-bug] commit message -These are analogous to submit@bugs.debian.org, nnn@bugs.debian.org, -and control@bugs.debian.org respectively. +by procmail, with matching emails being piped into ``be-handle-mail`` +for execution. + +Once ``be-handle-mail`` receives the email, the parsing method is +selected according to the subject tag that procmail used grab the +email in the first place. There are four parsing styles: + + +--------------------+----------------------------------+ + | Style | Subject | + +====================+==================================+ + | creating bugs | [be-bug:submit] new bug summary | + +--------------------+----------------------------------+ + | commenting on bugs | [be-bug:<bug-id>] commit message | + +--------------------+----------------------------------+ + | control | [be-bug] commit message | + +--------------------+----------------------------------+ + +These are analogous to ``submit@bugs.debian.org``, +``nnn@bugs.debian.org``, and ``control@bugs.debian.org`` respectively. Creating bugs ============= This interface creates a bug whose summary is given by the email's post-tag subject. The body of the email must begin with a -pseudo-header containing at least the "Version" field. Anything after -the pseudo-header and before a line starting with '--' is, if present, -attached as the bug's first comment. +pseudo-header containing at least the ``Version`` field. Anything after +the pseudo-header and before a line starting with ``--`` is, if present, +attached as the bug's first comment.:: From jdoe@example.com Fri Apr 18 12:00:00 2008 From: John Doe <jdoe@example.com> @@ -51,22 +57,22 @@ attached as the bug's first comment. Severity: minor Someone should write up a series of test emails to send into - be-handle mail so we can test changes quickly without having to + be-handle-mail so we can test changes quickly without having to use procmail. -- Goofy tagline not included. -Available pseudo-headers are Version, Reporter, Assign, Depend, -Severity, Status, Tag, and Target. +Available pseudo-headers are ``Version``, ``Reporter``, ``Assign``, +``Depend``, ``Severity``, ``Status``, ``Tag``, and ``Target``. Commenting on bugs ================== This interface appends a comment to the bug specified in the subject tag. The the first non-multipart body is attached with the -appropriate content-type. In the case of "text/plain" contents, -anything following a line starting with '--' is stripped. +appropriate content-type. In the case of ``text/plain`` contents, +anything following a line starting with ``--`` is stripped.:: From jdoe@example.com Fri Apr 18 12:00:00 2008 From: John Doe <jdoe@example.com> @@ -85,11 +91,11 @@ Controlling bugs ================ This interface consists of a list of allowed be commands, with one -command per line. Blank lines and lines beginning with '#' are -ignored, as well anything following a line starting with '--'. All +command per line. Blank lines and lines beginning with ``#`` are +ignored, as well anything following a line starting with ``--``. All the listed commands are executed in order and their output returned. The commands are split into arguments with the POSIX-compliant -shlex.split(). +shlex.split().:: From jdoe@example.com Fri Apr 18 12:00:00 2008 From: John Doe <jdoe@example.com> @@ -109,37 +115,42 @@ shlex.split(). Example emails ============== -Take a look at my interfaces/email/interactive/examples for some +Take a look at ``interfaces/email/interactive/examples`` for some more examples. Procmail rules ============== -The file _procmailrc as it stands is fairly appropriate for as a -dedicated user's ~/.procmailrc. It forwards matching mail to -be-handle-mail, which should be installed somewhere in the user's -path. All non-matching mail is dumped into /dev/null. Everything -procmail does will be logged to ~/be-mail/procmail.log. +The file ``_procmailrc`` as it stands is fairly appropriate for as a +dedicated user's ``~/.procmailrc``. It forwards matching mail to +``be-handle-mail``, which should be installed somewhere in the user's +path. All non-matching mail is dumped into ``/dev/null``. Everything +procmail does will be logged to ``~/be-mail/procmail.log``. If you're piggybacking the interface on top of an existing account, -you probably only need to add the be-handle-mail stanza to your -existing ~/.procmailrc, since you will still want to receive non-bug -emails. +you probably only need to add the ``be-handle-mail`` stanza to your +existing ``~/.procmailrc``, since you will still want to receive +non-bug emails. -Note that you will probably have to add a - --be-dir /path/to/served/repository -option to the be-handle-mail invocation so it knows what repository to +Note that you will probably have to add a:: + + --repo /path/to/served/repository + +option to the ``be-handle-mail`` invocation so it knows what repository to serve. Multiple repositories may be served by the same email address by adding -multiple be-handle-mail stanzas, each matching a different tag, for -example the "[be-bug" portion of the stanza could be "[projectX-bug", -"[projectY-bug", etc. If you change the base tag, be sure to add a - --tag-base "projectX-bug" -or equivalent to your be-handle-mail invocation. +multiple ``be-handle-mail`` stanzas, each matching a different tag, for +example the ``[be-bug`` portion of the stanza could be ``[projectX-bug``, +``[projectY-bug``, etc. If you change the base tag, be sure to add a:: + + --tag-base "projectX-bug" + +or equivalent to your ``be-handle-mail`` invocation. Testing ======= -Send test emails in to be-handle-mail with something like - cat examples/blank | ./be-handle-mail -o -l - -a +Send test emails in to ``be-handle-mail`` with something like:: + + cat examples/blank | ./be-handle-mail -o -l - -a diff --git a/libbe/command/comment.py b/libbe/command/comment.py index 16b0e77..cb46398 100644 --- a/libbe/command/comment.py +++ b/libbe/command/comment.py @@ -32,6 +32,7 @@ class Comment (libbe.command.Command): >>> import time >>> import libbe.bugdir + >>> import libbe.util.id >>> bd = libbe.bugdir.SimpleBugDir(memory=False) >>> io = libbe.command.StringInputOutput() >>> io.stdout = sys.stdout @@ -39,8 +40,12 @@ class Comment (libbe.command.Command): >>> ui.storage_callbacks.set_storage(bd.storage) >>> cmd = Comment(ui=ui) + >>> uuid_gen = libbe.util.id.uuid_gen + >>> libbe.util.id.uuid_gen = lambda: 'X' >>> ui._user_id = u'Fran\\xe7ois' >>> ret = ui.run(cmd, args=['/a', 'This is a comment about a']) + Created comment with ID abc/a/X + >>> libbe.util.id.uuid_gen = uuid_gen >>> bd.flush_reload() >>> bug = bd.bug_from_uuid('a') >>> bug.load_comments(load_full=False) @@ -65,7 +70,10 @@ class Comment (libbe.command.Command): UserError: No comment supplied, and EDITOR not specified. >>> os.environ['EDITOR'] = "echo 'I like cheese' > " + >>> libbe.util.id.uuid_gen = lambda: 'Y' >>> ret = ui.run(cmd, args=['/b']) + Created comment with ID abc/b/Y + >>> libbe.util.id.uuid_gen = uuid_gen >>> bd.flush_reload() >>> bug = bd.bug_from_uuid('b') >>> bug.load_comments(load_full=False) @@ -142,7 +150,8 @@ class Comment (libbe.command.Command): new = parent.new_reply(body=body) for key in ['alt-id', 'author', 'content-type']: if params[key] != None: - setattr(new, key, params[key]) + setattr(new, new._setting_name_to_attr_name(key), params[key]) + print >> self.stdout, 'Created comment with ID %s' % new.id.user() return 0 def _long_help(self): diff --git a/libbe/command/list.py b/libbe/command/list.py index 73c60a9..3803257 100644 --- a/libbe/command/list.py +++ b/libbe/command/list.py @@ -104,6 +104,8 @@ class List (libbe.command.Command): arg=libbe.command.Argument( name='severity', metavar='SEVERITY', default='all', completion_callback=libbe.command.util.complete_severity)), + libbe.command.Option(name='important', + help='List bugs with >= "serious" severity'), libbe.command.Option(name='assigned', short_name='a', help='Only show bugs matching ASSIGNED', arg=libbe.command.Argument( @@ -133,7 +135,6 @@ class List (libbe.command.Command): # help="Adjust bug-sort criteria with comma-separated list SORT-BY. e.g. \"--sort creator,time\". Available criteria: %s" % ','.join(AVAILABLE_CMPS), default=None) # # boolean options. All but ids and xml are special cases of long forms # ("w", "wishlist", "List bugs with 'wishlist' severity"), -# ("i", "important", "List bugs with >= 'serious' severity"), # ("A", "active", "List all active bugs"), # ("U", "unconfirmed", "List unconfirmed bugs"), # ("o", "open", "List open bugs"), @@ -202,7 +203,7 @@ class List (libbe.command.Command): severity.append(list(libbe.bug.severity_values[serious:])) else: severity = libbe.command.util.select_values( - params['severity'], bug.severity_values) + params['severity'], libbe.bug.severity_values) # select assigned if params['assigned'] == None: if params['mine'] == True: @@ -245,12 +246,12 @@ class List (libbe.command.Command): def _long_help(self): return """ This command lists bugs. Normally it prints a short string like - 576:om: Allow attachments + bea/576:om: Allow attachments Where - 576 the bug id - o the bug status is 'open' (first letter) - m the bug severity is 'minor' (first letter) - Allo... the bug summary string + bea/576 the bug id + o the bug status is 'open' (first letter) + m the bug severity is 'minor' (first letter) + Allo... the bug summary string You can optionally (-u) print only the bug ids. diff --git a/libbe/command/subscribe.py b/libbe/command/subscribe.py index bd36639..d1cf72e 100644 --- a/libbe/command/subscribe.py +++ b/libbe/command/subscribe.py @@ -92,7 +92,7 @@ class Subscribe (libbe.command.Command): libbe.command.Option(name='list', short_name='l', help='List subscribers (read only action).'), libbe.command.Option(name='subscriber', short_name='s', - help='Email address of the subscriber (defaults to bugdir.user_id).', + help='Email address of the subscriber (defaults to your user id).', arg=libbe.command.Argument( name='subscriber', metavar='EMAIL')), libbe.command.Option(name='servers', short_name='S', diff --git a/libbe/command/target.py b/libbe/command/target.py index 6bb348f..f8a956b 100644 --- a/libbe/command/target.py +++ b/libbe/command/target.py @@ -112,7 +112,7 @@ class Target (libbe.command.Command): def usage(self): return 'usage: be %(name)s BUG-ID [TARGET]\nor: be %(name)s --resolve [TARGET]' \ - % vars(self) + % vars(self.__class__) def _long_help(self): return """ diff --git a/libbe/comment.py b/libbe/comment.py index accd4df..21118f0 100644 --- a/libbe/comment.py +++ b/libbe/comment.py @@ -26,6 +26,13 @@ import os.path import sys import time import types +try: + from email.mime.base import MIMEBase + from email.encoders import encode_base64 +except ImportError: + # adjust to old python 2.4 + from email.MIMEBase import MIMEBase + from email.Encoders import encode_base64 try: # import core module, Python >= 2.5 from xml.etree import ElementTree except ImportError: # look for non-core module @@ -289,9 +296,9 @@ class Comment (Tree, settings_object.SavedSettingsObject): body = (self.body or '').rstrip('\n') else: maintype,subtype = self.content_type.split('/',1) - msg = email.mime.base.MIMEBase(maintype, subtype) + msg = MIMEBase(maintype, subtype) msg.set_payload(self.body or '') - email.encoders.encode_base64(msg) + encode_base64(msg) body = base64.encodestring(self.body or '') info = [('uuid', self.uuid), ('alt-id', self.alt_id), diff --git a/libbe/diff.py b/libbe/diff.py index 94a2dc3..35e2151 100644 --- a/libbe/diff.py +++ b/libbe/diff.py @@ -671,4 +671,7 @@ class Diff (object): return self._comment_summary_string(new_comment) def comment_body_change_string(self, bodies): old_body,new_body = bodies - return difflib.unified_diff(old_body, new_body) + return ''.join(difflib.unified_diff( + old_body.splitlines(True), + new_body.splitlines(True), + 'before', 'after')) @@ -21,6 +21,6 @@ setup( 'libbe.util'], scripts=['be'], data_files=[ - ('share/man/man1', ['doc/be.1']), + ('share/man/man1', ['doc/src/be.1']), ] ) |