aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile94
-rw-r--r--doc/conf.py198
-rw-r--r--doc/distributed_bugtracking.txt (renamed from doc/distributed_bugtracking)33
-rw-r--r--doc/doc.txt23
l---------doc/email.txt (renamed from doc/tutorial-email)0
-rw-r--r--doc/generate-libbe-txt.py52
-rw-r--r--doc/hacking.txt (renamed from doc/README.dev)11
-rw-r--r--doc/html.txt (renamed from doc/tutorial-html)4
-rw-r--r--doc/index.txt39
-rw-r--r--doc/install.txt55
-rw-r--r--doc/man/be.1.sgml (renamed from doc/src/be.1.sgml)0
-rw-r--r--doc/man/module.mk (renamed from doc/src/module.mk)0
-rw-r--r--doc/spam34
-rw-r--r--doc/spam.txt60
-rw-r--r--doc/tutorial.txt (renamed from doc/tutorial)101
15 files changed, 579 insertions, 125 deletions
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..6d7bbc5
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,94 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = .build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+ @echo " libbe to autogenerate files for all libbe modules"
+
+clean:
+ -rm -rf $(BUILDDIR) libbe
+
+html: libbe
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml: libbe
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+pickle: libbe
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json: libbe
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp: libbe
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp: libbe
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/bugs-everywhere.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/bugs-everywhere.qhc"
+
+latex: libbe
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+changes: libbe
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck: libbe
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest: libbe
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY : libbe
+libbe :
+ python generate-libbe-txt.py
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..1090a28
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,198 @@
+# -*- coding: utf-8 -*-
+#
+# bugs-everywhere documentation build configuration file, created by
+# sphinx-quickstart on Fri Feb 5 20:02:21 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
+
+import libbe.version
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage',
+ 'numpydoc']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.txt'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'bugs-everywhere'
+copyright = u'2010, W. Trevor King'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = libbe.version.version()
+# The full version, including alpha/beta/rc tags.
+release = libbe.version.version()
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = ['.build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['.static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'bugs-everywheredoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'bugs-everywhere.tex', u'bugs-everywhere Documentation',
+ u'W. Trevor King', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
diff --git a/doc/distributed_bugtracking b/doc/distributed_bugtracking.txt
index 1164c14..5ca42a6 100644
--- a/doc/distributed_bugtracking
+++ b/doc/distributed_bugtracking.txt
@@ -1,29 +1,40 @@
+***********************
+Distributed Bugtracking
+***********************
+
Usage Cases
===========
Case 1: Tracking the status of bugs in remote repo branches
-----------------------------------------------------------
-See discussion in
- #bea86499-824e-4e77-b085-2d581fa9ccab/12c986be-d19a-4b8b-b1b5-68248ff4d331#
+See the discussion in
+#bea86499-824e-4e77-b085-2d581fa9ccab/12c986be-d19a-4b8b-b1b5-68248ff4d331#.
Here, it doesn't matter whether the remote repository is a branch of
the local repository, or a completely separate project
(e.g. upstream, ...). So long as the remote project provides access
-via some REPO format, you can use
- be --repo REPO ...
-to run your query, or
- be diff REPO
+via some REPO format, you can use::
+
+ $ be --repo REPO ...
+
+to run your query, or::
+
+ $ be diff REPO
+
to see the changes between the local and remote repositories.
Case 2: Importing bugs from other repositories
----------------------------------------------
-Case 2.1: If the remote repository is a branch of the local repository
- VCS merge REPO
+Case 2.1: If the remote repository is a branch of the local repository::
+
+ $ <VCS> merge <REPO>
+
Case 2.2: If the remote repository is not a branch of the local repository
- Hypothetical command:
- be import REPO ID
+(Hypothetical command)::
+
+ $ be import <REPO> <ID>
Notes
@@ -42,5 +53,5 @@ Managing permissions
Many bugtrackers implement some sort of permissions system, and they
are certainly required for a central system with diverse user roles.
-However DVCSs also support the 'pull my changes' workflow, where
+However DVCSs also support the "pull my changes" workflow, where
permissions are irrelevant.
diff --git a/doc/doc.txt b/doc/doc.txt
new file mode 100644
index 0000000..e1b7a3a
--- /dev/null
+++ b/doc/doc.txt
@@ -0,0 +1,23 @@
+****************************
+Producing this documentation
+****************************
+
+This documentation is written in reStructuredText_, and produced
+using Sphinx_ and the numpydoc_ extension. The documentation source
+should be fairly readable without processing, but you can compile the
+documentation, you'll need to install Sphinx and numpydoc::
+
+ $ easy_install Sphinx
+ $ easy_install numpydoc
+
+.. _Sphinx: http://sphinx.pocoo.org/
+.. _numpydoc: http://pypi.python.org/pypi/numpydoc
+
+See the reStructuredText quick reference and the `NumPy/SciPy
+documentation guide`_ for an introduction to the documentation
+syntax.
+
+.. _reStructuredText:
+ http://docutils.sourceforge.net/docs/user/rst/quickref.html
+.. _NumPy/SciPy documentation guide:
+ http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
diff --git a/doc/tutorial-email b/doc/email.txt
index b25875f..b25875f 120000
--- a/doc/tutorial-email
+++ b/doc/email.txt
diff --git a/doc/generate-libbe-txt.py b/doc/generate-libbe-txt.py
new file mode 100644
index 0000000..35eb5c4
--- /dev/null
+++ b/doc/generate-libbe-txt.py
@@ -0,0 +1,52 @@
+#!/usr/bin/python
+#
+# Copyright
+
+"""Auto-generate reStructuredText of the libbe module tree for Sphinx.
+"""
+
+import sys
+import os, os.path
+
+sys.path.insert(0, os.path.abspath('..'))
+from test import python_tree
+
+def title(modname):
+ t = ':mod:`%s`' % modname
+ delim = '*'*len(t)
+ return '\n'.join([delim, t, delim, '', ''])
+
+def automodule(modname):
+ return '\n'.join([
+ '.. automodule:: %s' % modname,
+ ' :members:',
+ ' :undoc-members:',
+ '', ''])
+
+def toctree(children):
+ if len(children) == 0:
+ return ''
+ return '\n'.join([
+ '.. toctree::',
+ ' :maxdepth: 2',
+ '',
+ ] + [
+ ' %s.txt' % c for c in sorted(children)
+ ] + ['', ''])
+
+def make_module_txt(modname, children):
+ filename = os.path.join('libbe', '%s.txt' % modname)
+ if not os.path.exists('libbe'):
+ os.mkdir('libbe')
+ if os.path.exists(filename):
+ return None # don't overwrite potentially hand-written files.
+ f = file(filename, 'w')
+ f.write(title(modname))
+ f.write(automodule(modname))
+ f.write(toctree(children))
+ f.close()
+
+if __name__ == '__main__':
+ pt = python_tree(root_path='../libbe', root_modname='libbe')
+ for node in pt.traverse():
+ make_module_txt(node.modname, [c.modname for c in node])
diff --git a/doc/README.dev b/doc/hacking.txt
index 67be177..5b075f9 100644
--- a/doc/README.dev
+++ 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 b/doc/html.txt
index 0822ebd..9e7f114 100644
--- a/doc/tutorial-html
+++ 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
new file mode 100644
index 0000000..30b0318
--- /dev/null
+++ b/doc/index.txt
@@ -0,0 +1,39 @@
+Welcome to the bugs-everywhere documentation!
+=============================================
+
+Bugs Everywhere (BE) is a bugtracker built on distributed version
+control. It works with Arch_, Bazaar_, Darcs_, Git_, and Mercurial_
+at the moment, but is easily extensible. It can also function with no
+VCS 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.
+
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ install.txt
+ tutorial.txt
+ email.txt
+ html.txt
+ distributed_bugtracking.txt
+ hacking.txt
+ spam.txt
+ libbe/libbe.txt
+ doc.txt
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/doc/install.txt b/doc/install.txt
new file mode 100644
index 0000000..b1d153e
--- /dev/null
+++ b/doc/install.txt
@@ -0,0 +1,55 @@
+*************
+Installing BE
+*************
+
+Bazaar repository
+=================
+
+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/
+
+
+Release tarballs
+================
+
+For those not interested in the cutting edge, or those who don't want
+to worry about installing Bazaar, we'll post release tarballs somewhere
+(once we actually make a release). After you've downloaded the release
+tarball, unpack it with::
+
+ $ tar -xzvf be-<VERSION>.tar.gz
+
+And install it with:::
+
+ $ cd be-<VERSION>
+ $ make install
+
+
+Distribution packages
+=====================
+
+Some distributions (Debian_ , Ubuntu_ , others?) package BE. If
+you're running one of those distributions, you can install the package
+with your regular package manager. For Debian, Ubuntu, and related
+distros, that's::
+
+ $ apt-get install bugs-everywhere
+
+.. _Debian: http://packages.debian.org/sid/bugs-everywhere
+.. _Ubuntu: http://packages.ubuntu.com/lucid/bugs-everywhere
diff --git a/doc/src/be.1.sgml b/doc/man/be.1.sgml
index a2df21f..a2df21f 100644
--- a/doc/src/be.1.sgml
+++ b/doc/man/be.1.sgml
diff --git a/doc/src/module.mk b/doc/man/module.mk
index ea4eacc..ea4eacc 100644
--- a/doc/src/module.mk
+++ b/doc/man/module.mk
diff --git a/doc/spam b/doc/spam
deleted file mode 100644
index 4d74580..0000000
--- a/doc/spam
+++ /dev/null
@@ -1,34 +0,0 @@
-Removing spam commits from the history
-======================================
-
-arch bzr darcs git hg none
-
-In the case that some spam or inappropriate comment makes its way
-through you interface, you can remove the offending commit XYZ with:
-
- If the offending commit is the last commit:
-
- arch:
- bzr: bzr uncommit && bzr revert
- darcs: darcs obliterate --last=1
- git: git reset --hard HEAD^
- hg: hg rollback && hg revert
-
- If the offending commit is not the last commit:
-
- arch:
- bzr: bzr rebase -r <XYZ+1>..-1 --onto before:XYZ .
- (requires bzr-rebase plugin, note, you have to increment XYZ by
- hand for <XYZ+1>, because bzr does not support "after:XYZ".)
- darcs: darcs obliterate --matches 'name XYZ'
- git: git rebase --onto XYZ~1 XYZ
- hg: -not-supported-
- (From http://hgbook.red-bean.com/read/finding-and-fixing-mistakes.html#id394667
- "Mercurial also does not provide a way to make a file or
- changeset completely disappear from history, because there is no
- way to enforce its disappearance")
-
-Note that all of these _change_the_repo_history_, so only do this on
-your interface-specific repo before it interacts with any other repo.
-Otherwise, you'll have to survive by cherry-picking only the good
-commits.
diff --git a/doc/spam.txt b/doc/spam.txt
new file mode 100644
index 0000000..39e7a86
--- /dev/null
+++ b/doc/spam.txt
@@ -0,0 +1,60 @@
+*****************
+Dealing with spam
+*****************
+
+In the case that some spam or inappropriate comment makes its way
+through you interface, you can (sometimes) remove the offending commit
+``XYZ``.
+
+
+If the offending commit is the last commit
+==========================================
+
++-------+----------------------------+
+| arch | |
++-------+----------------------------+
+| bzr | bzr uncommit && bzr revert |
++-------+----------------------------+
+| darcs | darcs obliterate --last=1 |
++-------+----------------------------+
+| git | git reset --hard HEAD^ |
++-------+----------------------------+
+| hg | hg rollback && hg revert |
++-------+----------------------------+
+
+If the offending commit is not the last commit
+==============================================
+
++----------+-----------------------------------------------+
+| arch | |
++----------+-----------------------------------------------+
+| bzr [#]_ | bzr rebase -r <XYZ+1>..-1 --onto before:XYZ . |
++----------+-----------------------------------------------+
+| darcs | darcs obliterate --matches 'name XYZ' |
++----------+-----------------------------------------------+
+| git | git rebase --onto XYZ~1 XYZ |
++----------+-----------------------------------------------+
+| hg [#]_ | |
++----------+-----------------------------------------------+
+
+.. [#] Requires the ```bzr-rebase`` plugin`_. Note, you have to
+ increment ``XYZ`` by hand for ``<XYZ+1>``, because ``bzr`` does not
+ support ``after:XYZ``.
+
+.. [#] From `Mercurial: The Definitive Guide`:
+
+ "Mercurial also does not provide a way to make a file or
+ changeset completely disappear from history, because there is no
+ way to enforce its disappearance"
+
+.. _bzr-rebase plugin: http://wiki.bazaar.canonical.com/Rebase
+.. _Mercurial: The Definitive Guide:
+ http://hgbook.red-bean.com/read/finding-and-fixing-mistakes.html#id394667
+
+Warnings about changing history
+===============================
+
+Note that all of these *change the repo history* , so only do this on
+your interface-specific repo before it interacts with any other repo.
+Otherwise, you'll have to survive by cherry-picking only the good
+commits.
diff --git a/doc/tutorial b/doc/tutorial.txt
index 5a91bcd..7932c9c 100644
--- a/doc/tutorial
+++ 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: 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::
@@ -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.
generated by cgit (git 2.34.1) at 2024-09-24 22:30:48 +0000