diff options
Diffstat (limited to 'doc')
| -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 |
7 files changed, 123 insertions, 86 deletions
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. |