--*- markdown -*-
+Bugs Everywhere
+===============
-Cherry Flavored Bugs Everywhere
-===============================
+This is Bugs Everywhere (BE), a bugtracker built on distributed version
+control. It works with Arch, Bazaar, Darcs, Git, Mercurial, and Monotone
+at the moment, but is easily extensible. It can also function with no
+VCS at all.
-CFBE is a quick web interface to [BugsEverywhere](http://bugseverywhere.org/). It's still very much a work-in-progress.
+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.
-Installing
-----------
-I intend to streamline the installation once I'm satisfied with the interface itself. For now, the install process goes something like this:
+Getting BE
+==========
-* Install [CherryPy](http://cherrypy.org/) if you don't have it.
-* Install [Jinja2](http://jinja.pocoo.org/2/) if you don't have it.
-* Install [BugsEverywhere](http://bugseverywhere.org/) if you don't have it.
-* Download a zip/tar of CFBE (or hg clone) from the [Mercurial repository](http://bitbucket.org/sjl/cherryflavoredbugseverywhere/).
-* Unzip (if you grabbed a zip) and put the folder in your Python site-packages directory (or put it anywhere and symlink it to site-packages).
-* Symlink `site-packages/cherryflavoredbugseverywhere/cfbe.py` to `/usr/ local/bin/cfbe`
-* Use `cfbe [project_root]` to start up the web interface for that project.
-* Visit http://localhost:8080/ in a browser.
+BE is available as a Git repository::
+
+ $ git clone git://gitorious.org/be/be.git be
+
+See the homepage_ for details. If you do branch the Git 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, 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. If you do use Sphinx,
+you'll need to install numpydoc_ for automatically generating API
+documentation. See the ``NumPy/SciPy documentation guide``_ for an
+introduction to the syntax.
+
+.. _reStructuredText:
+ http://docutils.sourceforge.net/docs/user/rst/quickref.html
+.. _Sphinx: http://sphinx.pocoo.org/
+.. _docutils: http://docutils.sourceforge.net/
+.. _numpydoc: http://pypi.python.org/pypi/numpydoc
+.. _NumPy/SciPy documentation guide:
+ https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
projects / be.git / blobdiff