From 4c6a1e6439293c7e584aef4fda0da1a3968fe7c9 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 19 Nov 2009 17:00:02 -0500 Subject: Ran the new update_copyright.py --- doc/module.mk | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/module.mk b/doc/module.mk index 7791f48..de33d6a 100644 --- a/doc/module.mk +++ b/doc/module.mk @@ -4,6 +4,7 @@ # Part of Bugs Everywhere, a distributed bug tracking system. # # Copyright (C) 2008-2009 Chris Ball +# Gianluca Montecchi # W. Trevor King # # This program is free software; you can redistribute it and/or modify -- cgit From 072a46eefb66733ae570a9fb9abbc9570461a490 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 29 Dec 2009 21:53:58 -0500 Subject: Emptied interfaces directory Mostly throwing out a bunch of outdated GUIs. The email interface hasn't been moved over to the new 'Command' format yet... --- doc/README.dev | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/SPAM | 34 +++++++++++++++++++++ 2 files changed, 130 insertions(+) create mode 100644 doc/README.dev create mode 100644 doc/SPAM (limited to 'doc') diff --git a/doc/README.dev b/doc/README.dev new file mode 100644 index 0000000..2a09463 --- /dev/null +++ b/doc/README.dev @@ -0,0 +1,96 @@ +Extending BE +============ + +To write a plugin, you simply create a new file in the becommands +directory. Take a look at one of the simpler plugins (e.g. open.py) +for an example of how that looks, and to start getting a feel for the +libbe interface. + +To fit into the current framework, your extension module should +provide the following elements: + __desc__ + A short string describing the purpose of your plugin + execute(args, manipulate_encodings=True, restrict_file_access=False, + dir=".") + The entry function for your plugin. args is everything from + sys.argv after the name of your plugin (e.g. for the command + `be open abc', args=['abc']). + + manipulate_encodings should be passed through to any calls to + bugdir.BugDir(). See the BugDir documentation for details. + + If restrict_file_access==True, you should call + cmdutil.restrict_file_access(bugdir, path) + before attempting to read or write a file. See the + restrict_file_access documentation for details. + + dir is a directory inside the repository of interest. + + Note: be supports command-completion. To avoid raising errors you + need to deal with possible '--complete' options and arguments. + See the 'Command completion' section below for more information. + help() + Return the string to be output by `be help ', + `be --help', etc. + +While that's all that's strictly necessary, many plugins (all the +current ones) use libbe.cmdutil.CmdOptionParser to provide a +consistent interface + get_parser() + Return an instance of CmdOptionParser(""). You can + alter the parser (e.g. add some more options) before returning it. + +Again, you can just browse around in becommands to get a feel for things. + + +Testing +------- + +Run any doctests in your plugin with + be$ python test.py +for example + be$ python test.py merge + + +Command completion +------------------ + +BE implements a general framework to make it easy to support command +completion for arbitrary plugins. In order to support this system, +all becommands should properly handle the '--complete' commandline +argument, returning a list of possible completions. For example + $ be --commands + lists options accepted by be and the names of all available becommands. + $ be list --commands + lists options accepted by becommand/list + $ be list --status --commands + lists arguments accepted by the becommand/list --status option + $ be show -- --commands + lists possible vals for the first positional argument of becommand/show +This is a lot of information, but command-line completion is really +convenient for the user. See becommand/list.py and becommand/show.py +for example implementations. The basic idea is to raise + cmdutil.GetCompletions(['list','of','possible','completions']) +once you've determined what that list should be. + +However, command completion is not critical. The first priority is to +implement the target functionality, with fancy shell sugar coming +later. In recognition of this, cmdutil provides the default_complete +function which ensures that if '--complete' is any one of the +arguments, options, or option-arguments, GetCompletions will be raised +with and empty list. + +Profiling +========= + +Find out which 20 calls take the most cumulative time (time of +execution + childrens' times). + + $ python -m cProfile -o profile be [command] [args] + $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)" + +It's often useful to toss a + import sys, traceback + print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:]) +into expensive functions (e.g. libbe.util.subproc.invoke()), if you're +not sure why they're being called. diff --git a/doc/SPAM b/doc/SPAM new file mode 100644 index 0000000..4d74580 --- /dev/null +++ b/doc/SPAM @@ -0,0 +1,34 @@ +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 ..-1 --onto before:XYZ . + (requires bzr-rebase plugin, note, you have to increment XYZ by + hand for , 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. -- cgit From 4d4283ecd654f1efb058cd7f7dba6be88b70ee92 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 1 Jan 2010 08:11:08 -0500 Subject: Updated copyright information --- doc/module.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/module.mk b/doc/module.mk index de33d6a..960f7c0 100644 --- a/doc/module.mk +++ b/doc/module.mk @@ -3,7 +3,7 @@ # doc/module.mk # Part of Bugs Everywhere, a distributed bug tracking system. # -# Copyright (C) 2008-2009 Chris Ball +# Copyright (C) 2008-2010 Chris Ball # Gianluca Montecchi # W. Trevor King # -- cgit From f08a1e8e195b37bef4bc78e5f66ae730c9ee061e Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sun, 3 Jan 2010 11:06:48 -0500 Subject: Added doc/distributed_bugtracking with some simple use-case notes --- doc/distributed_bugtracking | 46 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 doc/distributed_bugtracking (limited to 'doc') diff --git a/doc/distributed_bugtracking b/doc/distributed_bugtracking new file mode 100644 index 0000000..1164c14 --- /dev/null +++ b/doc/distributed_bugtracking @@ -0,0 +1,46 @@ +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# +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 +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.2: If the remote repository is not a branch of the local repository + Hypothetical command: + be import REPO ID + + +Notes +===== + +Providing public repositories +----------------------------- + +e.g. for non-dev users. These are just branches that expose a public +interface (HTML, email, ...). Merge and query like any other +development branch. + + +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 +permissions are irrelevant. -- cgit From 04cd30589f138704e9cf88ee37f6549733cbe7e1 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 23 Jan 2010 11:40:11 -0500 Subject: Reorganized documentation to clean doc/ for user-readable files --- doc/SPAM | 34 -------------- doc/be.1.sgml | 134 ------------------------------------------------------ doc/module.mk | 44 ------------------ doc/spam | 34 ++++++++++++++ doc/src/be.1.sgml | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/src/module.mk | 44 ++++++++++++++++++ doc/tutorial | 1 + 7 files changed, 213 insertions(+), 212 deletions(-) delete mode 100644 doc/SPAM delete mode 100644 doc/be.1.sgml delete mode 100644 doc/module.mk create mode 100644 doc/spam create mode 100644 doc/src/be.1.sgml create mode 100644 doc/src/module.mk create mode 100644 doc/tutorial (limited to 'doc') 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 ..-1 --onto before:XYZ . - (requires bzr-rebase plugin, note, you have to increment XYZ by - hand for , 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/be.1.sgml b/doc/be.1.sgml deleted file mode 100644 index a2df21f..0000000 --- a/doc/be.1.sgml +++ /dev/null @@ -1,134 +0,0 @@ - manpage.1'. You may view - the manual page with: `docbook-to-man manpage.sgml | nroff -man | - less'. A typical entry in a Makefile or Makefile.am is: - -be.1: be.1.sgml - docbook-to-man $< > $@ - - The docbook-to-man binary is found in the docbook-to-man package. - Please remember that if you create the nroff version in one of the - debian/rules file targets (such as build), you will need to include - docbook-to-man in your Build-Depends control field. - - --> - - Ben"> - Finney"> - - 2009-06-25"> - - 1"> - ben+debian@benfinney.id.au"> - - BUGS-EVERYWHERE"> - - - BE"> - - - Debian"> - GNU"> - GPL"> -]> - - - -
- &dhemail; -
- - &dhfirstname; - &dhsurname; - - - 2009 - &dhusername; - - &dhdate; - - - &uccmdname; - - &dhsection; - - - &cmdname; - - distributed bug tracker - - - - &cmdname; - command - command_options ... - command_args ... - - - &cmdname; help - - - &cmdname; help - command - - - - DESCRIPTION - - This manual page documents briefly the - &cmdname; command, part of the - &pkgfullname; package. - - &cmdname; allows commandline interaction - with the &pkgfullname; database in a project tree. - - - - COMMANDS - - - help - - - Print help for be and a list of all available commands. - - - - - - - AUTHOR - - This manual page was written by &dhusername; <&dhemail;> for - the &debian; system (but may be used by others). Permission is - granted to copy, distribute and/or modify this document under - the terms of the &gnu; General Public License, Version 2 or any - later version published by the Free Software Foundation. - - - On Debian systems, the complete text of the GNU General Public - License can be found in /usr/share/common-licenses/GPL. - - - - - - diff --git a/doc/module.mk b/doc/module.mk deleted file mode 100644 index 960f7c0..0000000 --- a/doc/module.mk +++ /dev/null @@ -1,44 +0,0 @@ -# :vim: filetype=make : -*- makefile; coding: utf-8; -*- - -# doc/module.mk -# Part of Bugs Everywhere, a distributed bug tracking system. -# -# Copyright (C) 2008-2010 Chris Ball -# Gianluca Montecchi -# W. Trevor King -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License along -# with this program; if not, write to the Free Software Foundation, Inc., -# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -# Makefile module for documentation - -MODULE_DIR := doc - -MANPAGES = be.1 -manpage_files = $(patsubst %,${MODULE_DIR}/%,${MANPAGES}) - -GENERATED_FILES += ${manpage_files} - - -.PHONY: doc -doc: man - -build: doc - - -.PHONY: man -man: ${manpage_files} - -%.1: %.1.sgml - docbook-to-man $< > $@ diff --git a/doc/spam b/doc/spam new file mode 100644 index 0000000..4d74580 --- /dev/null +++ b/doc/spam @@ -0,0 +1,34 @@ +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 ..-1 --onto before:XYZ . + (requires bzr-rebase plugin, note, you have to increment XYZ by + hand for , 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/src/be.1.sgml b/doc/src/be.1.sgml new file mode 100644 index 0000000..a2df21f --- /dev/null +++ b/doc/src/be.1.sgml @@ -0,0 +1,134 @@ + manpage.1'. You may view + the manual page with: `docbook-to-man manpage.sgml | nroff -man | + less'. A typical entry in a Makefile or Makefile.am is: + +be.1: be.1.sgml + docbook-to-man $< > $@ + + The docbook-to-man binary is found in the docbook-to-man package. + Please remember that if you create the nroff version in one of the + debian/rules file targets (such as build), you will need to include + docbook-to-man in your Build-Depends control field. + + --> + + Ben"> + Finney"> + + 2009-06-25"> + + 1"> + ben+debian@benfinney.id.au"> + + BUGS-EVERYWHERE"> + + + BE"> + + + Debian"> + GNU"> + GPL"> +]> + + + +
+ &dhemail; +
+ + &dhfirstname; + &dhsurname; + + + 2009 + &dhusername; + + &dhdate; + + + &uccmdname; + + &dhsection; + + + &cmdname; + + distributed bug tracker + + + + &cmdname; + command + command_options ... + command_args ... + + + &cmdname; help + + + &cmdname; help + command + + + + DESCRIPTION + + This manual page documents briefly the + &cmdname; command, part of the + &pkgfullname; package. + + &cmdname; allows commandline interaction + with the &pkgfullname; database in a project tree. + + + + COMMANDS + + + help + + + Print help for be and a list of all available commands. + + + + + + + AUTHOR + + This manual page was written by &dhusername; <&dhemail;> for + the &debian; system (but may be used by others). Permission is + granted to copy, distribute and/or modify this document under + the terms of the &gnu; General Public License, Version 2 or any + later version published by the Free Software Foundation. + + + On Debian systems, the complete text of the GNU General Public + License can be found in /usr/share/common-licenses/GPL. + + + + + + diff --git a/doc/src/module.mk b/doc/src/module.mk new file mode 100644 index 0000000..ea4eacc --- /dev/null +++ b/doc/src/module.mk @@ -0,0 +1,44 @@ +# :vim: filetype=make : -*- makefile; coding: utf-8; -*- + +# doc/module.mk +# Part of Bugs Everywhere, a distributed bug tracking system. +# +# Copyright (C) 2008-2010 Chris Ball +# Gianluca Montecchi +# W. Trevor King +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program; if not, write to the Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +# Makefile module for documentation + +MODULE_DIR := doc/src + +MANPAGES = be.1 +manpage_files = $(patsubst %,${MODULE_DIR}/%,${MANPAGES}) + +GENERATED_FILES += ${manpage_files} + + +.PHONY: doc +doc: man + +build: doc + + +.PHONY: man +man: ${manpage_files} + +%.1: %.1.sgml + docbook-to-man $< > $@ diff --git a/doc/tutorial b/doc/tutorial new file mode 100644 index 0000000..1333ed7 --- /dev/null +++ b/doc/tutorial @@ -0,0 +1 @@ +TODO -- cgit From 53074356bf715c820d3b9b852cd45e5073ba765d Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sun, 24 Jan 2010 11:20:47 -0500 Subject: Rewrote documentation --- doc/README.dev | 69 +++++---- doc/tutorial | 443 ++++++++++++++++++++++++++++++++++++++++++++++++++++- doc/tutorial-email | 1 + doc/tutorial-html | 3 + 4 files changed, 484 insertions(+), 32 deletions(-) create mode 120000 doc/tutorial-email create mode 100644 doc/tutorial-html (limited to 'doc') diff --git a/doc/README.dev b/doc/README.dev index a2b8d30..cfb1896 100644 --- a/doc/README.dev +++ b/doc/README.dev @@ -4,61 +4,68 @@ Extending 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 plugins (e.g. remove.py) -for an example of how that looks, and to start getting a feel for the -libbe interface. +To write a plugin, you simply create a new file in the +``libbe/commands/`` directory. Take a look at one of the simpler +plugins (e.g. ``remove.py``) for an example of how that looks, and to +start getting a feel for the libbe interface. -See libbe/commands/base.py for the definition of the important classes -Option, Argument, Command, InputOutput, StorageCallbacks, and -UserInterface classes. You'll be subclassing Command for your -command, but all those classes will be important. +See ``libbe/commands/base.py`` for the definition of the important +classes ``Option``, ``Argument``, ``Command``, ``InputOutput``, +``StorageCallbacks``, and ``UserInterface`` classes. You'll be +subclassing ``Command`` for your command, but all those classes will +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, -any of your completable Argument() instances (in your commands -.options or .args) should be initialized with some valid +any of your completable ``Argument()`` instances (in your command's +``.options`` or ``.args``) should be initialized with some valid completion_callback function. Some common cases are defined in -libbe.command.util. If you need more flexibility, see -libbe.command.list's "--sort" option for an example of extensions via -libbe.command.util.Completer, or write a custom completion function -from scratch. +``libbe.command.util``. If you need more flexibility, see +``libbe.command.list``'s ``--sort`` option for an example of +extensions via ``libbe.command.util.Completer``, or write a custom +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. -More details to come after I write an HTML ui... +Take a look at ``libbe/ui/command_line.py`` for an example. Basically +you'll need to setup a ``UserInterface`` instance for running commands. +More details to come after I write an HTML UI... Testing ======= -Run any tests in your module with - be$ python test.py -for example - be$ python test.py libbe.command.merge +Run any tests in your module with:: -For a definition of "any tests", see test.py's add_module_tests() -function. + be$ python test.py + +for example: + + be$ python test.py libbe.command.merge + +For a definition of "any tests", see ``test.py``'s +``add_module_tests()`` function. Profiling ========= Find out which 20 calls take the most cumulative time (time of -execution + childrens' times). +execution + childrens' times):: + + $ python -m cProfile -o profile be [command] [args] + $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)" + +It's often useful to toss:: - $ python -m cProfile -o profile be [command] [args] - $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)" + import sys, traceback + print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:]) -It's often useful to toss a - import sys, traceback - print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:]) -into expensive functions (e.g. libbe.util.subproc.invoke()), if you're -not sure why they're being called. +into expensive functions (e.g. ``libbe.util.subproc.invoke()``) if +you're not sure why they're being called. diff --git a/doc/tutorial b/doc/tutorial index 1333ed7..5a91bcd 100644 --- a/doc/tutorial +++ b/doc/tutorial @@ -1 +1,442 @@ -TODO +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: ../doc/tutorial-html +.. _email: ../doc/tutorial-email + +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 + + + +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 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 + +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 ' '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 + + + ... + +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 + +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. + +Currently, we only expose ``be commit``, which commits all currently +pending changes. + + +IDs +--- + +Format +~~~~~~ + +BE IDs are formatted:: + + [/[/]] + +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"). diff --git a/doc/tutorial-email b/doc/tutorial-email new file mode 120000 index 0000000..b25875f --- /dev/null +++ b/doc/tutorial-email @@ -0,0 +1 @@ +../interfaces/email/interactive/README \ No newline at end of file diff --git a/doc/tutorial-html b/doc/tutorial-html new file mode 100644 index 0000000..0822ebd --- /dev/null +++ b/doc/tutorial-html @@ -0,0 +1,3 @@ +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. -- cgit From d2752cde56e7cf67abc2e7f0a0fc91612016585f Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 27 Jan 2010 08:22:22 -0500 Subject: Encourage a run of `make` to build auto-generated files. Fixes Ben's "unintuitive test procedure" bug: Date: Wed, 27 Jan 2010 14:09:14 +1100 From: Ben Finney Subject: [Be-devel] Re: Test suite on Trevor's development branch ... > $ python ./test.py > Traceback (most recent call last): [...] > ImportError: No module named _version So it's not possible to simply get a copy of the branch and try running the test suite. ... --- doc/README.dev | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc') diff --git a/doc/README.dev b/doc/README.dev index cfb1896..67be177 100644 --- a/doc/README.dev +++ b/doc/README.dev @@ -52,6 +52,9 @@ for example: For a definition of "any tests", see ``test.py``'s ``add_module_tests()`` function. +Note that you will need to run ``make`` before testing a clean BE +branch to auto-generate required files like ``libbe/_version.py``. + Profiling ========= -- cgit From f3e912e4a9a532bb7a0e528ff74c55ce0484fc01 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 5 Feb 2010 20:06:02 -0500 Subject: Created Sphinx framework with sphinx-quickstart and added .txt extensiosns --- doc/Makefile | 89 ++++++++ doc/README.dev | 74 ------- doc/conf.py | 194 ++++++++++++++++++ doc/distributed_bugtracking | 46 ----- doc/distributed_bugtracking.txt | 46 +++++ doc/hacking.txt | 74 +++++++ doc/index.txt | 20 ++ doc/spam | 34 ---- doc/spam.txt | 34 ++++ doc/tutorial | 442 ---------------------------------------- doc/tutorial-email | 1 - doc/tutorial-email.txt | 1 + doc/tutorial-html | 3 - doc/tutorial-html.txt | 3 + doc/tutorial.txt | 442 ++++++++++++++++++++++++++++++++++++++++ 15 files changed, 903 insertions(+), 600 deletions(-) create mode 100644 doc/Makefile delete mode 100644 doc/README.dev create mode 100644 doc/conf.py delete mode 100644 doc/distributed_bugtracking create mode 100644 doc/distributed_bugtracking.txt create mode 100644 doc/hacking.txt create mode 100644 doc/index.txt delete mode 100644 doc/spam create mode 100644 doc/spam.txt delete mode 100644 doc/tutorial delete mode 120000 doc/tutorial-email create mode 120000 doc/tutorial-email.txt delete mode 100644 doc/tutorial-html create mode 100644 doc/tutorial-html.txt create mode 100644 doc/tutorial.txt (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..df8818c --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,89 @@ +# 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 ' where 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)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(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: + $(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: + $(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: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(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: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/README.dev b/doc/README.dev deleted file mode 100644 index 67be177..0000000 --- a/doc/README.dev +++ /dev/null @@ -1,74 +0,0 @@ -Extending 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 -plugins (e.g. ``remove.py``) for an example of how that looks, and to -start getting a feel for the libbe interface. - -See ``libbe/commands/base.py`` for the definition of the important -classes ``Option``, ``Argument``, ``Command``, ``InputOutput``, -``StorageCallbacks``, and ``UserInterface`` classes. You'll be -subclassing ``Command`` for your command, but all those classes will -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, -any of your completable ``Argument()`` instances (in your command's -``.options`` or ``.args``) should be initialized with some valid -completion_callback function. Some common cases are defined in -``libbe.command.util``. If you need more flexibility, see -``libbe.command.list``'s ``--sort`` option for an example of -extensions via ``libbe.command.util.Completer``, or write a custom -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. -More details to come after I write an HTML UI... - - -Testing -======= - -Run any tests in your module with:: - - be$ python test.py - -for example: - - be$ python test.py libbe.command.merge - -For a definition of "any tests", see ``test.py``'s -``add_module_tests()`` function. - -Note that you will need to run ``make`` before testing a clean BE -branch to auto-generate required files like ``libbe/_version.py``. - - -Profiling -========= - -Find out which 20 calls take the most cumulative time (time of -execution + childrens' times):: - - $ python -m cProfile -o profile be [command] [args] - $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)" - -It's often useful to toss:: - - import sys, traceback - print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:]) - -into expensive functions (e.g. ``libbe.util.subproc.invoke()``) if -you're not sure why they're being called. diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..68b279f --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,194 @@ +# -*- 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('.')) + +# -- 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'] + +# 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 = '432' +# The full version, including alpha/beta/rc tags. +release = '432' + +# 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 +# " v 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 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 deleted file mode 100644 index 1164c14..0000000 --- a/doc/distributed_bugtracking +++ /dev/null @@ -1,46 +0,0 @@ -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# -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 -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.2: If the remote repository is not a branch of the local repository - Hypothetical command: - be import REPO ID - - -Notes -===== - -Providing public repositories ------------------------------ - -e.g. for non-dev users. These are just branches that expose a public -interface (HTML, email, ...). Merge and query like any other -development branch. - - -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 -permissions are irrelevant. diff --git a/doc/distributed_bugtracking.txt b/doc/distributed_bugtracking.txt new file mode 100644 index 0000000..1164c14 --- /dev/null +++ b/doc/distributed_bugtracking.txt @@ -0,0 +1,46 @@ +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# +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 +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.2: If the remote repository is not a branch of the local repository + Hypothetical command: + be import REPO ID + + +Notes +===== + +Providing public repositories +----------------------------- + +e.g. for non-dev users. These are just branches that expose a public +interface (HTML, email, ...). Merge and query like any other +development branch. + + +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 +permissions are irrelevant. diff --git a/doc/hacking.txt b/doc/hacking.txt new file mode 100644 index 0000000..67be177 --- /dev/null +++ b/doc/hacking.txt @@ -0,0 +1,74 @@ +Extending 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 +plugins (e.g. ``remove.py``) for an example of how that looks, and to +start getting a feel for the libbe interface. + +See ``libbe/commands/base.py`` for the definition of the important +classes ``Option``, ``Argument``, ``Command``, ``InputOutput``, +``StorageCallbacks``, and ``UserInterface`` classes. You'll be +subclassing ``Command`` for your command, but all those classes will +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, +any of your completable ``Argument()`` instances (in your command's +``.options`` or ``.args``) should be initialized with some valid +completion_callback function. Some common cases are defined in +``libbe.command.util``. If you need more flexibility, see +``libbe.command.list``'s ``--sort`` option for an example of +extensions via ``libbe.command.util.Completer``, or write a custom +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. +More details to come after I write an HTML UI... + + +Testing +======= + +Run any tests in your module with:: + + be$ python test.py + +for example: + + be$ python test.py libbe.command.merge + +For a definition of "any tests", see ``test.py``'s +``add_module_tests()`` function. + +Note that you will need to run ``make`` before testing a clean BE +branch to auto-generate required files like ``libbe/_version.py``. + + +Profiling +========= + +Find out which 20 calls take the most cumulative time (time of +execution + childrens' times):: + + $ python -m cProfile -o profile be [command] [args] + $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)" + +It's often useful to toss:: + + import sys, traceback + print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:]) + +into expensive functions (e.g. ``libbe.util.subproc.invoke()``) if +you're not sure why they're being called. diff --git a/doc/index.txt b/doc/index.txt new file mode 100644 index 0000000..0aca57c --- /dev/null +++ b/doc/index.txt @@ -0,0 +1,20 @@ +.. 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 bugs-everywhere's documentation! +=========================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + 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 ..-1 --onto before:XYZ . - (requires bzr-rebase plugin, note, you have to increment XYZ by - hand for , 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..4d74580 --- /dev/null +++ b/doc/spam.txt @@ -0,0 +1,34 @@ +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 ..-1 --onto before:XYZ . + (requires bzr-rebase plugin, note, you have to increment XYZ by + hand for , 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/tutorial b/doc/tutorial deleted file mode 100644 index 5a91bcd..0000000 --- a/doc/tutorial +++ /dev/null @@ -1,442 +0,0 @@ -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: ../doc/tutorial-html -.. _email: ../doc/tutorial-email - -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 - - - -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 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 - -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 ' '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 - - - ... - -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 - -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. - -Currently, we only expose ``be commit``, which commits all currently -pending changes. - - -IDs ---- - -Format -~~~~~~ - -BE IDs are formatted:: - - [/[/]] - -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"). diff --git a/doc/tutorial-email b/doc/tutorial-email deleted file mode 120000 index b25875f..0000000 --- a/doc/tutorial-email +++ /dev/null @@ -1 +0,0 @@ -../interfaces/email/interactive/README \ No newline at end of file diff --git a/doc/tutorial-email.txt b/doc/tutorial-email.txt new file mode 120000 index 0000000..b25875f --- /dev/null +++ b/doc/tutorial-email.txt @@ -0,0 +1 @@ +../interfaces/email/interactive/README \ No newline at end of file diff --git a/doc/tutorial-html b/doc/tutorial-html deleted file mode 100644 index 0822ebd..0000000 --- a/doc/tutorial-html +++ /dev/null @@ -1,3 +0,0 @@ -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/tutorial-html.txt b/doc/tutorial-html.txt new file mode 100644 index 0000000..0822ebd --- /dev/null +++ b/doc/tutorial-html.txt @@ -0,0 +1,3 @@ +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/tutorial.txt b/doc/tutorial.txt new file mode 100644 index 0000000..5a91bcd --- /dev/null +++ b/doc/tutorial.txt @@ -0,0 +1,442 @@ +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: ../doc/tutorial-html +.. _email: ../doc/tutorial-email + +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 + + + +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 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 + +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 ' '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 + + + ... + +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 + +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. + +Currently, we only expose ``be commit``, which commits all currently +pending changes. + + +IDs +--- + +Format +~~~~~~ + +BE IDs are formatted:: + + [/[/]] + +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"). -- cgit From 52999e64546aa1ca5aba14e16311d5487dbb6ac1 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 5 Feb 2010 20:08:22 -0500 Subject: Moved manpage source doc/src to doc/man --- doc/man/be.1.sgml | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/man/module.mk | 44 ++++++++++++++++++ doc/src/be.1.sgml | 134 ------------------------------------------------------ doc/src/module.mk | 44 ------------------ 4 files changed, 178 insertions(+), 178 deletions(-) create mode 100644 doc/man/be.1.sgml create mode 100644 doc/man/module.mk delete mode 100644 doc/src/be.1.sgml delete mode 100644 doc/src/module.mk (limited to 'doc') diff --git a/doc/man/be.1.sgml b/doc/man/be.1.sgml new file mode 100644 index 0000000..a2df21f --- /dev/null +++ b/doc/man/be.1.sgml @@ -0,0 +1,134 @@ + manpage.1'. You may view + the manual page with: `docbook-to-man manpage.sgml | nroff -man | + less'. A typical entry in a Makefile or Makefile.am is: + +be.1: be.1.sgml + docbook-to-man $< > $@ + + The docbook-to-man binary is found in the docbook-to-man package. + Please remember that if you create the nroff version in one of the + debian/rules file targets (such as build), you will need to include + docbook-to-man in your Build-Depends control field. + + --> + + Ben"> + Finney"> + + 2009-06-25"> + + 1"> + ben+debian@benfinney.id.au"> + + BUGS-EVERYWHERE"> + + + BE"> + + + Debian"> + GNU"> + GPL"> +]> + + + +
+ &dhemail; +
+ + &dhfirstname; + &dhsurname; + + + 2009 + &dhusername; + + &dhdate; + + + &uccmdname; + + &dhsection; + + + &cmdname; + + distributed bug tracker + + + + &cmdname; + command + command_options ... + command_args ... + + + &cmdname; help + + + &cmdname; help + command + + + + DESCRIPTION + + This manual page documents briefly the + &cmdname; command, part of the + &pkgfullname; package. + + &cmdname; allows commandline interaction + with the &pkgfullname; database in a project tree. + + + + COMMANDS + + + help + + + Print help for be and a list of all available commands. + + + + + + + AUTHOR + + This manual page was written by &dhusername; <&dhemail;> for + the &debian; system (but may be used by others). Permission is + granted to copy, distribute and/or modify this document under + the terms of the &gnu; General Public License, Version 2 or any + later version published by the Free Software Foundation. + + + On Debian systems, the complete text of the GNU General Public + License can be found in /usr/share/common-licenses/GPL. + + + + + + diff --git a/doc/man/module.mk b/doc/man/module.mk new file mode 100644 index 0000000..1eb6955 --- /dev/null +++ b/doc/man/module.mk @@ -0,0 +1,44 @@ +# :vim: filetype=make : -*- makefile; coding: utf-8; -*- + +# doc/module.mk +# Part of Bugs Everywhere, a distributed bug tracking system. +# +# Copyright (C) 2008-2010 Chris Ball +# Gianluca Montecchi +# W. Trevor King +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program; if not, write to the Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +# Makefile module for documentation + +MODULE_DIR := doc/man + +MANPAGES = be.1 +manpage_files = $(patsubst %,${MODULE_DIR}/%,${MANPAGES}) + +GENERATED_FILES += ${manpage_files} + + +.PHONY: doc +doc: man + +build: doc + + +.PHONY: man +man: ${manpage_files} + +%.1: %.1.sgml + docbook-to-man $< > $@ diff --git a/doc/src/be.1.sgml b/doc/src/be.1.sgml deleted file mode 100644 index a2df21f..0000000 --- a/doc/src/be.1.sgml +++ /dev/null @@ -1,134 +0,0 @@ - manpage.1'. You may view - the manual page with: `docbook-to-man manpage.sgml | nroff -man | - less'. A typical entry in a Makefile or Makefile.am is: - -be.1: be.1.sgml - docbook-to-man $< > $@ - - The docbook-to-man binary is found in the docbook-to-man package. - Please remember that if you create the nroff version in one of the - debian/rules file targets (such as build), you will need to include - docbook-to-man in your Build-Depends control field. - - --> - - Ben"> - Finney"> - - 2009-06-25"> - - 1"> - ben+debian@benfinney.id.au"> - - BUGS-EVERYWHERE"> - - - BE"> - - - Debian"> - GNU"> - GPL"> -]> - - - -
- &dhemail; -
- - &dhfirstname; - &dhsurname; - - - 2009 - &dhusername; - - &dhdate; - - - &uccmdname; - - &dhsection; - - - &cmdname; - - distributed bug tracker - - - - &cmdname; - command - command_options ... - command_args ... - - - &cmdname; help - - - &cmdname; help - command - - - - DESCRIPTION - - This manual page documents briefly the - &cmdname; command, part of the - &pkgfullname; package. - - &cmdname; allows commandline interaction - with the &pkgfullname; database in a project tree. - - - - COMMANDS - - - help - - - Print help for be and a list of all available commands. - - - - - - - AUTHOR - - This manual page was written by &dhusername; <&dhemail;> for - the &debian; system (but may be used by others). Permission is - granted to copy, distribute and/or modify this document under - the terms of the &gnu; General Public License, Version 2 or any - later version published by the Free Software Foundation. - - - On Debian systems, the complete text of the GNU General Public - License can be found in /usr/share/common-licenses/GPL. - - - - - - diff --git a/doc/src/module.mk b/doc/src/module.mk deleted file mode 100644 index ea4eacc..0000000 --- a/doc/src/module.mk +++ /dev/null @@ -1,44 +0,0 @@ -# :vim: filetype=make : -*- makefile; coding: utf-8; -*- - -# doc/module.mk -# Part of Bugs Everywhere, a distributed bug tracking system. -# -# Copyright (C) 2008-2010 Chris Ball -# Gianluca Montecchi -# W. Trevor King -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License along -# with this program; if not, write to the Free Software Foundation, Inc., -# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -# Makefile module for documentation - -MODULE_DIR := doc/src - -MANPAGES = be.1 -manpage_files = $(patsubst %,${MODULE_DIR}/%,${MANPAGES}) - -GENERATED_FILES += ${manpage_files} - - -.PHONY: doc -doc: man - -build: doc - - -.PHONY: man -man: ${manpage_files} - -%.1: %.1.sgml - docbook-to-man $< > $@ -- cgit From 4109434843ecdf2e73a010fcbb37cc3d404ef8ef Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 5 Feb 2010 20:09:58 -0500 Subject: Sphynx now gets version string automatically. --- doc/conf.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/conf.py b/doc/conf.py index 68b279f..b2dab25 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -13,6 +13,8 @@ import sys, os +import libbe.version + # 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. @@ -45,9 +47,9 @@ copyright = u'2010, W. Trevor King' # built documents. # # The short X.Y version. -version = '432' +version = libbe.version.version() # The full version, including alpha/beta/rc tags. -release = '432' +release = libbe.version.version() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit From da8309e67c669b1cca5d39c8e7da34c9b431bef6 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 6 Feb 2010 09:47:20 -0500 Subject: Added page titles to the documentation & adjusted section levels. --- doc/distributed_bugtracking.txt | 4 ++ doc/email.txt | 1 + doc/hacking.txt | 11 +++-- doc/html.txt | 7 +++ doc/index.txt | 84 ++++++++++++++++++++++++++++++--- doc/spam.txt | 5 ++ doc/tutorial-email.txt | 1 - doc/tutorial-html.txt | 3 -- doc/tutorial.txt | 101 +++++++++++----------------------------- 9 files changed, 127 insertions(+), 90 deletions(-) create mode 120000 doc/email.txt create mode 100644 doc/html.txt delete mode 120000 doc/tutorial-email.txt delete mode 100644 doc/tutorial-html.txt (limited to 'doc') diff --git a/doc/distributed_bugtracking.txt b/doc/distributed_bugtracking.txt index 1164c14..f3d574c 100644 --- a/doc/distributed_bugtracking.txt +++ b/doc/distributed_bugtracking.txt @@ -1,3 +1,7 @@ +*********************** +Distributed Bugtracking +*********************** + Usage Cases =========== diff --git a/doc/email.txt b/doc/email.txt new file mode 120000 index 0000000..b25875f --- /dev/null +++ b/doc/email.txt @@ -0,0 +1 @@ +../interfaces/email/interactive/README \ No newline at end of file diff --git a/doc/hacking.txt b/doc/hacking.txt index 67be177..5b075f9 100644 --- a/doc/hacking.txt +++ 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/html.txt b/doc/html.txt new file mode 100644 index 0000000..9e7f114 --- /dev/null +++ b/doc/html.txt @@ -0,0 +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 index 0aca57c..55ee543 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -1,16 +1,35 @@ -.. 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 ================== @@ -18,3 +37,56 @@ 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/ diff --git a/doc/spam.txt b/doc/spam.txt index 4d74580..c0a2ba3 100644 --- a/doc/spam.txt +++ b/doc/spam.txt @@ -1,3 +1,8 @@ +***************** +Dealing with spam +***************** + + Removing spam commits from the history ====================================== diff --git a/doc/tutorial-email.txt b/doc/tutorial-email.txt deleted file mode 120000 index b25875f..0000000 --- a/doc/tutorial-email.txt +++ /dev/null @@ -1 +0,0 @@ -../interfaces/email/interactive/README \ No newline at end of file diff --git a/doc/tutorial-html.txt b/doc/tutorial-html.txt deleted file mode 100644 index 0822ebd..0000000 --- a/doc/tutorial-html.txt +++ /dev/null @@ -1,3 +0,0 @@ -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/tutorial.txt b/doc/tutorial.txt index 5a91bcd..3dd7ff3 100644 --- a/doc/tutorial.txt +++ 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: ids.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:: - - [/[/]] - -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. -- cgit From 23b523c3ddd527012f0ae18dc2b3da2fadcfdae2 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 6 Feb 2010 11:06:32 -0500 Subject: Broke out install.txt + reStructuredText markup fixes --- doc/distributed_bugtracking.txt | 29 ++++++++------ doc/index.txt | 63 +++---------------------------- doc/install.txt | 55 +++++++++++++++++++++++++++ doc/spam.txt | 83 ++++++++++++++++++++++++++--------------- 4 files changed, 130 insertions(+), 100 deletions(-) create mode 100644 doc/install.txt (limited to 'doc') 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:: + + $ merge + 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 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-.tar.gz + +And install it with::: + + $ cd be- + $ 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 ..-1 --onto before:XYZ . - (requires bzr-rebase plugin, note, you have to increment XYZ by - hand for , 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 ..-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 ````, 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. -- cgit From 668be5b01d9ad47f4f9714bfe8deee377341eb35 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 6 Feb 2010 13:09:24 -0500 Subject: Added libbe.bug to the Sphinx documentation --- doc/conf.py | 5 +++-- doc/ids.txt | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/index.txt | 2 +- doc/libbe.bug.txt | 7 +++++++ doc/libbe.txt | 12 ++++++++++++ 5 files changed, 76 insertions(+), 3 deletions(-) create mode 100644 doc/ids.txt create mode 100644 doc/libbe.bug.txt create mode 100644 doc/libbe.txt (limited to 'doc') diff --git a/doc/conf.py b/doc/conf.py index b2dab25..ea03b08 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -13,12 +13,13 @@ import sys, os -import libbe.version - # 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 ----------------------------------------------------- diff --git a/doc/ids.txt b/doc/ids.txt new file mode 100644 index 0000000..ba1837b --- /dev/null +++ b/doc/ids.txt @@ -0,0 +1,53 @@ +********** +Object IDs +********** + +Format +====== + +BE IDs are formatted:: + + [/[/]] + +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"). diff --git a/doc/index.txt b/doc/index.txt index f1c1542..9c964fa 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -29,7 +29,7 @@ Contents: distributed_bugtracking.txt hacking.txt spam.txt - + libbe.txt Indices and tables ================== diff --git a/doc/libbe.bug.txt b/doc/libbe.bug.txt new file mode 100644 index 0000000..41427c5 --- /dev/null +++ b/doc/libbe.bug.txt @@ -0,0 +1,7 @@ +**************** +:mod:`libbe.bug` +**************** + +.. automodule:: libbe.bug + :members: + :undoc-members: diff --git a/doc/libbe.txt b/doc/libbe.txt new file mode 100644 index 0000000..dd04df1 --- /dev/null +++ b/doc/libbe.txt @@ -0,0 +1,12 @@ +************ +:mod:`libbe` +************ + +.. automodule:: libbe + :members: + :undoc-members: + +.. toctree:: + :maxdepth: 2 + + libbe.bug.txt -- cgit From 4c71190ebafd7ce198a5c0047588c4b2f7e5ef58 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 6 Feb 2010 13:44:05 -0500 Subject: Added bugdir and comment modules to Sphinx docs --- doc/libbe.bugdir.txt | 7 +++++++ doc/libbe.comment.txt | 7 +++++++ doc/libbe.txt | 2 ++ 3 files changed, 16 insertions(+) create mode 100644 doc/libbe.bugdir.txt create mode 100644 doc/libbe.comment.txt (limited to 'doc') diff --git a/doc/libbe.bugdir.txt b/doc/libbe.bugdir.txt new file mode 100644 index 0000000..2464ea6 --- /dev/null +++ b/doc/libbe.bugdir.txt @@ -0,0 +1,7 @@ +******************* +:mod:`libbe.bugdir` +******************* + +.. automodule:: libbe.bugdir + :members: + :undoc-members: diff --git a/doc/libbe.comment.txt b/doc/libbe.comment.txt new file mode 100644 index 0000000..6e76f98 --- /dev/null +++ b/doc/libbe.comment.txt @@ -0,0 +1,7 @@ +******************** +:mod:`libbe.comment` +******************** + +.. automodule:: libbe.comment + :members: + :undoc-members: diff --git a/doc/libbe.txt b/doc/libbe.txt index dd04df1..5d29434 100644 --- a/doc/libbe.txt +++ b/doc/libbe.txt @@ -9,4 +9,6 @@ .. toctree:: :maxdepth: 2 + libbe.bugdir.txt libbe.bug.txt + libbe.comment.txt -- cgit From 413626d3b77e9bf89389a272ed489da29f3d9877 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 6 Feb 2010 16:53:57 -0500 Subject: Use numpydoc and generate-libbe-txt.py to autogenerate API documentation --- doc/conf.py | 3 ++- doc/doc.txt | 23 +++++++++++++++++++++ doc/generate-libbe-txt.py | 52 +++++++++++++++++++++++++++++++++++++++++++++++ doc/index.txt | 9 ++++---- doc/libbe.bug.txt | 7 ------- doc/libbe.bugdir.txt | 7 ------- doc/libbe.comment.txt | 7 ------- doc/libbe.txt | 14 ------------- 8 files changed, 82 insertions(+), 40 deletions(-) create mode 100644 doc/doc.txt create mode 100644 doc/generate-libbe-txt.py delete mode 100644 doc/libbe.bug.txt delete mode 100644 doc/libbe.bugdir.txt delete mode 100644 doc/libbe.comment.txt delete mode 100644 doc/libbe.txt (limited to 'doc') diff --git a/doc/conf.py b/doc/conf.py index ea03b08..1090a28 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -25,7 +25,8 @@ import libbe.version # 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'] +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'] 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/generate-libbe-txt.py b/doc/generate-libbe-txt.py new file mode 100644 index 0000000..ec874fa --- /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 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/index.txt b/doc/index.txt index 9c964fa..6765a68 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -2,9 +2,9 @@ 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. +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/ @@ -29,7 +29,8 @@ Contents: distributed_bugtracking.txt hacking.txt spam.txt - libbe.txt + libbe/libbe.txt + doc.txt Indices and tables ================== diff --git a/doc/libbe.bug.txt b/doc/libbe.bug.txt deleted file mode 100644 index 41427c5..0000000 --- a/doc/libbe.bug.txt +++ /dev/null @@ -1,7 +0,0 @@ -**************** -:mod:`libbe.bug` -**************** - -.. automodule:: libbe.bug - :members: - :undoc-members: diff --git a/doc/libbe.bugdir.txt b/doc/libbe.bugdir.txt deleted file mode 100644 index 2464ea6..0000000 --- a/doc/libbe.bugdir.txt +++ /dev/null @@ -1,7 +0,0 @@ -******************* -:mod:`libbe.bugdir` -******************* - -.. automodule:: libbe.bugdir - :members: - :undoc-members: diff --git a/doc/libbe.comment.txt b/doc/libbe.comment.txt deleted file mode 100644 index 6e76f98..0000000 --- a/doc/libbe.comment.txt +++ /dev/null @@ -1,7 +0,0 @@ -******************** -:mod:`libbe.comment` -******************** - -.. automodule:: libbe.comment - :members: - :undoc-members: diff --git a/doc/libbe.txt b/doc/libbe.txt deleted file mode 100644 index 5d29434..0000000 --- a/doc/libbe.txt +++ /dev/null @@ -1,14 +0,0 @@ -************ -:mod:`libbe` -************ - -.. automodule:: libbe - :members: - :undoc-members: - -.. toctree:: - :maxdepth: 2 - - libbe.bugdir.txt - libbe.bug.txt - libbe.comment.txt -- cgit From 977eff5af10b50ba6e6edb6abc4f40804c418b12 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sun, 7 Feb 2010 17:53:53 -0500 Subject: Fixed docstrings so only Sphinx errors are "autosummary" and "missing attribute" --- doc/generate-libbe-txt.py | 2 +- doc/ids.txt | 53 ----------------------------------------------- doc/index.txt | 1 - doc/tutorial.txt | 2 +- 4 files changed, 2 insertions(+), 56 deletions(-) delete mode 100644 doc/ids.txt (limited to 'doc') diff --git a/doc/generate-libbe-txt.py b/doc/generate-libbe-txt.py index ec874fa..35eb5c4 100644 --- a/doc/generate-libbe-txt.py +++ b/doc/generate-libbe-txt.py @@ -31,7 +31,7 @@ def toctree(children): ' :maxdepth: 2', '', ] + [ - ' %s.txt' % c for c in children + ' %s.txt' % c for c in sorted(children) ] + ['', '']) def make_module_txt(modname, children): diff --git a/doc/ids.txt b/doc/ids.txt deleted file mode 100644 index ba1837b..0000000 --- a/doc/ids.txt +++ /dev/null @@ -1,53 +0,0 @@ -********** -Object IDs -********** - -Format -====== - -BE IDs are formatted:: - - [/[/]] - -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"). diff --git a/doc/index.txt b/doc/index.txt index 6765a68..30b0318 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -23,7 +23,6 @@ Contents: install.txt tutorial.txt - ids.txt email.txt html.txt distributed_bugtracking.txt diff --git a/doc/tutorial.txt b/doc/tutorial.txt index 3dd7ff3..7932c9c 100644 --- a/doc/tutorial.txt +++ b/doc/tutorial.txt @@ -24,7 +24,7 @@ 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: ids.txt +.. _IDs: libbe/libbe.util.id.txt Installation ============ -- cgit From 960565a8cc80f98d0a8bfa77029fbc78692ea1a1 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Mon, 8 Feb 2010 17:02:56 -0500 Subject: Consolidated Makefile and doc/man/module.mk. Incorperated doc/Makefile. Now make sphinx builds the Sphinx HTML documentation (in doc/.build/html), and make clean cleans up everything. Having a separate module.mk was just making things confusing, so I took it out ;). --- doc/Makefile | 27 ++++++++++++++++----------- doc/man/module.mk | 44 -------------------------------------------- 2 files changed, 16 insertions(+), 55 deletions(-) delete mode 100644 doc/man/module.mk (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile index df8818c..6d7bbc5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -26,37 +26,38 @@ help: @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)/* + -rm -rf $(BUILDDIR) libbe -html: +html: libbe $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -dirhtml: +dirhtml: libbe $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." -pickle: +pickle: libbe $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." -json: +json: libbe $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." -htmlhelp: +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: +qthelp: libbe $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ @@ -65,25 +66,29 @@ qthelp: @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/bugs-everywhere.qhc" -latex: +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: +changes: libbe $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." -linkcheck: +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: +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/man/module.mk b/doc/man/module.mk deleted file mode 100644 index 1eb6955..0000000 --- a/doc/man/module.mk +++ /dev/null @@ -1,44 +0,0 @@ -# :vim: filetype=make : -*- makefile; coding: utf-8; -*- - -# doc/module.mk -# Part of Bugs Everywhere, a distributed bug tracking system. -# -# Copyright (C) 2008-2010 Chris Ball -# Gianluca Montecchi -# W. Trevor King -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License along -# with this program; if not, write to the Free Software Foundation, Inc., -# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -# Makefile module for documentation - -MODULE_DIR := doc/man - -MANPAGES = be.1 -manpage_files = $(patsubst %,${MODULE_DIR}/%,${MANPAGES}) - -GENERATED_FILES += ${manpage_files} - - -.PHONY: doc -doc: man - -build: doc - - -.PHONY: man -man: ${manpage_files} - -%.1: %.1.sgml - docbook-to-man $< > $@ -- cgit