aboutsummaryrefslogtreecommitdiffstats
path: root/doc/tutorial.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/tutorial.txt')
-rw-r--r--doc/tutorial.txt101
1 files changed, 26 insertions, 75 deletions
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.