aboutsummaryrefslogtreecommitdiffstats
path: root/doc/tutorial.txt
diff options
context:
space:
mode:
authorGianluca Montecchi <gian@grys.it>2010-02-10 00:03:38 +0100
committerGianluca Montecchi <gian@grys.it>2010-02-10 00:03:38 +0100
commitc67a5863826771001f009e1ee90262ccb7a2e172 (patch)
tree64c7f83238685959bf40a13c876168071a085556 /doc/tutorial.txt
parenta60e599798d43ba930efc1f8e2f184d3e8262189 (diff)
parent50444209eee408dde7d240fdf59bfc9e82b714ce (diff)
downloadbugseverywhere-c67a5863826771001f009e1ee90262ccb7a2e172.tar.gz
Merged Trevor's tree
Diffstat (limited to 'doc/tutorial.txt')
-rw-r--r--doc/tutorial.txt393
1 files changed, 393 insertions, 0 deletions
diff --git a/doc/tutorial.txt b/doc/tutorial.txt
new file mode 100644
index 0000000..7932c9c
--- /dev/null
+++ b/doc/tutorial.txt
@@ -0,0 +1,393 @@
+********
+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: tutorial-html.txt
+.. _email: tutorial-email.txt
+.. _IDs: libbe/libbe.util.id.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::
+
+ $ 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.
+
+Commit
+~~~~~~
+
+Currently, we only expose ``be commit``, which commits all currently
+pending changes.