3 ## Debian Bug-Tracking System ##
5 ********************************
7 ### What is Debbugs ###
8 Debbugs is a stable, scaleable bug reporting and issue tracking system. Debbugs has a web interface for viewing and searching issues in the database but unlike other bug tracking systems, Debbugs has no web interface for editing bug reports - all modification is done via email.
10 The most notable deployment of Debbugs is on the [Debian project](https://www.debian.org/Bugs/)
12 ### System Requirements ###
16 * Perl 5 (5.005 is known to work)
17 * Mailtools and MIME-tools perl modules to manipulate email
19 * The bug system requires its own mail domain. It comes with code
20 which understands how exim, qmail and sendmail deliver mail for such a
22 * A webserver. For the old system of static HTML pages generated for
23 bug reports and index pages, this is easiest if the bug system can
24 write directly to the webspace; for the new system of CGI scripts
25 that generate web pages on the fly, write access is not required.
26 * Somewhere to run CGI scripts (unless you don't need the web forms for
27 searching for bugs by number, package, maintainer or submitter).
29 ### Where do I get the Source? ###
31 Debbugs is managed in git. You can clone the repository into your local
34 git clone http://bugs-master.debian.org/debbugs-source/debbugs.git
36 Additional branches are available from:
38 * [Don Armstrong](http://git.donarmstrong.com/debbugs.git/)
40 ### Installation Instructions ###
42 Install the Debian package and read `/usr/share/doc/debbugs/README.Debian` file.
44 If you can't use the `.deb`, do the following:
48 git clone http://bugs-master.debian.org/debbugs-source/debbugs.git
50 2. Create version and spool directory
55 3. Optional - Retrieve a partial database of bugs for testing
57 It's useful to have some bugs in the database for testing our new Debbugs instance.
59 1. Get a list of rsync targets from Debbugs
61 rsync --list-only rsync://bugs-mirror.debian.org
63 2. Grab bugs ending in 00
65 mkdir -p splool/db-h/00;
67 rsync -av rsync://bugs-mirror.debian.org/bts-spool-db/00 .;
69 4. Optional - Retrieve bts-versions directory for testing purposes
71 Required for testing using test database retrieved at 3.
73 1. Pull versions directory
76 rsync -av rsync://bugs-mirror.debian.org/bts-versions/ versions/
78 2. Pull index directory
80 rsync -av rsync://bugs-mirror.debian.org/bts-spool-index index
82 5. Configure Debbugs config
84 1. Create a config directory for Debbugs
86 sudo mkdir /etc/debbugs
88 2. Copy sample configuration to config directory
90 sudo cp ~/debbugs/scripts/config.debian /etc/debbugs/config
92 3. Update the following variables
102 < $gConfigDir = "/org/bugs.debian.org/etc"; # directory where this file is
103 < $gSpoolDir = "/org/bugs.debian.org/spool"; # working directory
104 < $gIndicesDir = "/org/bugs.debian.org/indices"; # directory where the indices are
106 > $gConfigDir = "/etc/debbugs"; # directory where this file is
107 > $gSpoolDir = "/path/to/directory/spool"; # working directory
108 > $gIndicesDir = "/path/to/directory/spool/indices"; # directory where the indices are
111 < $gWebDir = "/org/bugs.debian.org/www"; # base location of web pages
112 < $gDocDir = "/org/ftp.debian.org/ftp/doc"; # location of text doc files
114 > $gWebDir = "/path/to/directory/debbugs/html"; # base location of web pages
115 > $gDocDir = "/path/to/directory/debbugs/doc"; # location of text doc files
117 6. Configure Webserver
119 1. Copy example apache config
121 sudo cp $HOME/debbugs/examples/apache.conf /etc/apache2/sites-available/debbugs.conf
123 2. Update the directory entries and the DocumentRoot and ScriptAlias variables
126 < DocumentRoot /var/lib/debbugs/www/
128 > DocumentRoot /path/to/directory/debbugs/html/
131 < <Directory /var/lib/debbugs/www>
133 > <Directory /path/to/directory/debbugs/html>
136 < ScriptAlias /cgi-bin/ /var/lib/debbugs/www/cgi/
137 < <Directory "/var/lib/debbugs/www/cgi/">
139 > ScriptAlias /cgi-bin/ /path/to/directory/debbugs/cgi/
140 > <Directory "/path/to/directory/debbugs/cgi/">
142 3. Enable required apache mods
149 sudo a2ensite debbugs
151 7. Install dependencies
153 sudo apt-get install libmailtools-perl ed libmime-tools-perl libio-stringy-perl libmldbm-perl liburi-perl libsoap-lite-perl libcgi-simple-perl libparams-validate-perl libtext-template-perl libsafe-hole-perl libmail-rfc822-address-perl liblist-moreutils-perl libtext-template-perl libfile-libmagic-perl libgravatar-url-perl libwww-perl imagemagick libapache2-mod-perl2
157 1. Create symlinks to link source to their expected locations
159 sudo mkdir -p /usr/local/lib/site_perl
160 sudo ln -s /path/to/directory/debbugs/Debbugs /usr/local/lib/site_perl/
162 sudo mkdir -p /usr/share/debbugs/
163 sudo ln -s /path/to/directory/debbugs/templates /usr/share/debbugs/
165 9. Create required files
169 touch /etc/debbugs/pseudo-packages.description
170 touch /etc/debbugs/Source_maintainers
171 touch /etc/debbugs/pseudo-packages.maintainers
172 touch /etc/debbugs/Maintainers
173 touch /etc/debbugs/Maintainers.override
174 mkdir /etc/debbugs/indices
175 touch /etc/debbugs/indices/sources
180 perl -c cgi/bugreport.cgi
181 REQUEST_METHOD=GET QUERY_STRING="bug=775300" perl cgi/bugreport.cgi;
183 10. Install MTA. See README.mail for details.
185 Note that each line of `/etc/debbugs/Maintainers` file needs to be formatted as
188 package maintainer name <email@address>
190 If you need a template, look in `/usr/share/doc/debbugs/examples/` directory.
192 ### How do I contribute to Debbugs? ###
194 #### Debbugs for Debbugs ####
196 Debbugs bugs are tracked using Debbugs. The web interface is available:
197 [Debbugs bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?repeatmerged=no&src=debbugs)
199 #### Start contributing ####
201 Make a working branch for your code and check it out to start working:
203 git checkout -b example-branch
205 Stage and commit your changes using appropriate commit messages
209 git commit -m "Created an example file to demonstrate basic git commands."
211 #### Submitting a Patch ####
213 Submitting a patch can be done using git format-patch.
217 git format-patch origin/master
219 Creates `.patch` files for all commits since the branch diverged from master.
221 Debbugs bugs are tracked using debbugs (what else). Patches should therefore be
222 attached to the bug report for the issue. This can be done by emailing the
223 `.patch` files to `xxxx@bugs.debian.org` (where xxxx is the bug number).
225 Feature patches can also be emailed to the maintaining list at
226 [Debugs mailing list](debian-debbugs@lists.debian.org)
228 ### Further Information and Assistance ###
232 * Mailing List <debian-debbugs@lists.debian.org>
234 * To subscribe to the mailing list, email
235 <debian-debbugs-request@lists.debian.org> with the word "subscribe" in the
240 * [Code](https://bugs.debian.org/debbugs-source/debbugs.git/)
241 * [Debbugs Team](https://wiki.debian.org/Teams/Debbugs|Debbugs Team)
245 Join the #debbugs channel on [OFTC](irc.oftc.net)
249 This bug tracking system was developed by Ian Jackson from 1994-1997,
250 with assistance from nCipher Corporation Limited in 1997. nCipher allowed
251 Ian to redistribute modifications he made to the system while working as an
254 Since then, it has been developed by the various administrators of
255 bugs.debian.org, including Darren Benham, Adam Heath, Josip Rodin, Anthony
256 Towns, and Colin Watson. As in the case of Ian, nCipher allowed Colin to
257 redistribute modifications he made while working as an employee of nCipher.
259 ### Copyright and Lack-of-Warranty Notice ###
261 * Copyright 1999 Darren O. Benham
262 * Copyright 1994-1997 Ian Jackson
263 * Copyright 1997,2003 nCipher Corporation Limited
265 This bug system is free software; you can redistribute it and/or modify it
266 under the terms of the GNU General Public License as published by the Free
267 Software Foundation; version 2 of the License.
269 This program and documentation is distributed in the hope that it will be
270 useful, but without any warranty; without even the implied warranty of
271 merchantability or fitness for a particular purpose. See the GNU General
272 Public License for more details.
274 You should have received a copy of the GNU General Public License along
275 with this program, or one should be available above; if not, write to the
276 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA