diff options
| -rw-r--r-- | README | 22 | ||||
| -rw-r--r-- | doc/distributed_bugtracking.txt | 4 | ||||
| l--------- | doc/email.txt (renamed from doc/tutorial-email.txt) | 0 | ||||
| -rw-r--r-- | doc/hacking.txt | 11 | ||||
| -rw-r--r-- | doc/html.txt (renamed from doc/tutorial-html.txt) | 4 | ||||
| -rw-r--r-- | doc/index.txt | 84 | ||||
| -rw-r--r-- | doc/spam.txt | 5 | ||||
| -rw-r--r-- | doc/tutorial.txt | 101 | ||||
| -rw-r--r-- | interfaces/email/interactive/README | 4 |
9 files changed, 138 insertions, 97 deletions
@@ -10,6 +10,7 @@ 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 numbers, bugs have globally unique ids. + Getting BE ========== @@ -38,8 +39,9 @@ Getting started To get started, you must set the bugtracker root. Typically, you will want to 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 +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 @@ -47,18 +49,16 @@ can can use ``be comment $BUG_ID``. To close a bug, use 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. +If ``be help`` isn't scratching your itch, the full documentation is +available in the doc directory as reStructuredText_ . You can build +the full documentation with Sphinx_ , convert single files with +docutils_ , or browse through the doc directory by hand. +doc/index.txt is a good place to start. .. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html +.. _Sphinx: http://sphinx.pocoo.org/ .. _docutils: http://docutils.sourceforge.net/ diff --git a/doc/distributed_bugtracking.txt b/doc/distributed_bugtracking.txt index 1164c14..f3d574c 100644 --- a/doc/distributed_bugtracking.txt +++ b/doc/distributed_bugtracking.txt @@ -1,3 +1,7 @@ +*********************** +Distributed Bugtracking +*********************** + Usage Cases =========== diff --git a/doc/tutorial-email.txt b/doc/email.txt index b25875f..b25875f 120000 --- a/doc/tutorial-email.txt +++ b/doc/email.txt diff --git a/doc/hacking.txt b/doc/hacking.txt index 67be177..5b075f9 100644 --- a/doc/hacking.txt +++ b/doc/hacking.txt @@ -1,8 +1,9 @@ -Extending BE -============ +********** +Hacking 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 @@ -17,7 +18,7 @@ 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, @@ -31,7 +32,7 @@ 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. diff --git a/doc/tutorial-html.txt b/doc/html.txt index 0822ebd..9e7f114 100644 --- a/doc/tutorial-html.txt +++ b/doc/html.txt @@ -1,3 +1,7 @@ +************** +HTML Interface +************** + 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/doc/index.txt b/doc/index.txt index 0aca57c..55ee543 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -1,16 +1,35 @@ -.. bugs-everywhere documentation master file, created by - sphinx-quickstart on Fri Feb 5 20:02:21 2010. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +Welcome to the bugs-everywhere documentation! +============================================= -Welcome to bugs-everywhere's documentation! -=========================================== +Bugs Everywhere (BE) is a bugtracker built on distributed revision +control. It works with Arch_ , Bazaar_ , Darcs_ , Git_ , and +Mercurial_ at the moment, but is easily extensible. It can also +function with no RCS at all. + +.. _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/ + +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 numbers, bugs have globally unique ids. Contents: .. toctree:: :maxdepth: 2 + tutorial.txt + ids.txt + email.txt + html.txt + distributed_bugtracking.txt + hacking.txt + spam.txt + + Indices and tables ================== @@ -18,3 +37,56 @@ Indices and tables * :ref:`modindex` * :ref:`search` +Getting BE +========== + +BE is available as a bzr repository:: + + $ bzr branch http://bzr.bugseverywhere.org/be + +See the homepage_ for details. If you do branch the bzr repo, you'll +need to run:: + + $ make + +to build some auto-generated files (e.g. ``libbe/_version.py``), and:: + + $ make install + +to install BE. By default BE will install into your home directory, +but you can tweak the ``PREFIX`` variable in ``Makefile`` to install +to another location. + +.. _homepage: http://bugseverywhere.org/ + + +Getting started +=============== + +To get started, you must set the bugtracker root. Typically, you will +want to 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``. + +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/spam.txt b/doc/spam.txt index 4d74580..c0a2ba3 100644 --- a/doc/spam.txt +++ b/doc/spam.txt @@ -1,3 +1,8 @@ +***************** +Dealing with spam +***************** + + Removing spam commits from the history ====================================== diff --git a/doc/tutorial.txt b/doc/tutorial.txt index 5a91bcd..3dd7ff3 100644 --- a/doc/tutorial.txt +++ b/doc/tutorial.txt @@ -1,8 +1,9 @@ +******** Tutorial -======== +******** Introduction ------------- +============ Bugs Everywhere (BE) is a bugtracker built on distributed revision control. The idea is to package the bug information with the source @@ -21,11 +22,12 @@ 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 +.. _web: tutorial-html.txt +.. _email: tutorial-email.txt +.. _IDs: ids.txt Installation ------------- +============ If your distribution packages BE, it will be easiest to use their package. For example, most Debian-based distributions support:: @@ -33,7 +35,7 @@ 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:: @@ -48,10 +50,10 @@ If your bug isn't listed, please open a new bug:: 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 @@ -70,7 +72,7 @@ for example:: 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 @@ -110,7 +112,7 @@ comment IDs in this tutorial will start with ``bea/``. Creating bugs -~~~~~~~~~~~~~ +------------- Create new bugs with:: @@ -136,7 +138,7 @@ 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 @@ -172,7 +174,7 @@ the content and why you're attaching it, so the above should have been 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 @@ -227,7 +229,7 @@ entries around, scripting BE, etc. ... Listing bugs -~~~~~~~~~~~~ +------------ If you *don't* know which bug you're interested in, you can query the whole bug directory:: @@ -240,7 +242,7 @@ 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 @@ -267,7 +269,7 @@ 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, @@ -285,7 +287,7 @@ 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 @@ -309,7 +311,7 @@ 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 @@ -330,7 +332,7 @@ 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:: @@ -347,7 +349,7 @@ 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:: @@ -358,7 +360,7 @@ 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:: @@ -376,7 +378,7 @@ 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 @@ -384,59 +386,8 @@ 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 +Commit ~~~~~~ -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"). +Currently, we only expose ``be commit``, which commits all currently +pending changes. diff --git a/interfaces/email/interactive/README b/interfaces/email/interactive/README index f7d57ad..48bccdd 100644 --- a/interfaces/email/interactive/README +++ b/interfaces/email/interactive/README @@ -1,3 +1,7 @@ +*************** +Email Interface +*************** + Overview ======== |