bugs can be marked "fixed" in the branches that fix them. So, instead of
numbers, bugs have globally unique ids.
+
Getting BE
==========
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
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/
+***********************
+Distributed Bugtracking
+***********************
+
Usage Cases
===========
-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
Command completion
-~~~~~~~~~~~~~~~~~~
+------------------
BE implements a general framework to make it easy to support command
completion for arbitrary plugins. In order to support this system,
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.
+**************
+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.
-.. 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
==================
* :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/
+*****************
+Dealing with spam
+*****************
+
+
Removing spam commits from the history
======================================
+********
Tutorial
-========
+********
Introduction
-------------
+============
Bugs Everywhere (BE) is a bugtracker built on distributed revision
control. The idea is to package the bug information with the source
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::
$ apt-get install bugs-everywhere
Bugs
-----
+====
If you have any problems with BE, you can look for matching bugs::
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
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
Creating bugs
-~~~~~~~~~~~~~
+-------------
Create new bugs with::
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
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
...
Listing bugs
-~~~~~~~~~~~~
+------------
If you *don't* know which bug you're interested in, you can query
the whole bug directory::
``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
$ 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,
``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
access.
Managing bug directories
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
``be set`` lets you configure a bug directory. You can set
$ be set target $(be target --resolve '1.2.3')
Import XML
-~~~~~~~~~~
+----------
For serializing bug information (e.g. to email to a mailing list), use::
.. _mbox: http://en.wikipedia.org/wiki/Mbox
Export HTML
-~~~~~~~~~~~
+-----------
To create a static dump of your bug directory, use::
the email_ interface for interactive access.
BE over HTTP
-~~~~~~~~~~~~
+------------
Besides using BE to work directly with local VCS-based repositories,
you can use::
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
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.
+***************
+Email Interface
+***************
+
Overview
========
projects / be.git / commitdiff