diff options
| -rw-r--r-- | README | 4 | ||||
| -rw-r--r-- | doc/distributed_bugtracking.txt | 29 | ||||
| -rw-r--r-- | doc/index.txt | 63 | ||||
| -rw-r--r-- | doc/install.txt | 55 | ||||
| -rw-r--r-- | doc/spam.txt | 83 |
5 files changed, 132 insertions, 102 deletions
@@ -1,9 +1,9 @@ Bugs Everywhere =============== -This is Bugs Everywhere (BE), a bugtracker built on distributed revision +This is Bugs Everywhere (BE), 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 RCS at +moment, but is easily extensible. It can also function with no VCS at all. The idea is to package the bug information with the source code, so that diff --git a/doc/distributed_bugtracking.txt b/doc/distributed_bugtracking.txt index f3d574c..5ca42a6 100644 --- a/doc/distributed_bugtracking.txt +++ b/doc/distributed_bugtracking.txt @@ -8,26 +8,33 @@ 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 @@ -46,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/index.txt b/doc/index.txt index 55ee543..f1c1542 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -1,10 +1,10 @@ Welcome to the bugs-everywhere documentation! ============================================= -Bugs Everywhere (BE) is a bugtracker built on distributed revision +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 RCS at all. +function with no VCS at all. .. _Arch: http://www.gnu.org/software/gnu-arch/ .. _Bazaar: http://bazaar.canonical.com/ @@ -13,14 +13,15 @@ function with no RCS at all. .. _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. +that bugs can be marked "fixed" in the branches that fix them. + Contents: .. toctree:: :maxdepth: 2 + install.txt tutorial.txt ids.txt email.txt @@ -36,57 +37,3 @@ Indices and tables * :ref:`genindex` * :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/ 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/spam.txt b/doc/spam.txt index c0a2ba3..39e7a86 100644 --- a/doc/spam.txt +++ b/doc/spam.txt @@ -2,38 +2,59 @@ Dealing with spam ***************** - -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 +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. |