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. Retrieve a partial database of bugs for testing
57 Optional - It is 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. Retrieve bts-versions directory for testing purposes
71 Optional - 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
100 < $gConfigDir = "/org/bugs.debian.org/etc"; # directory where this file is
101 < $gSpoolDir = "/org/bugs.debian.org/spool"; # working directory
102 < $gIndicesDir = "/org/bugs.debian.org/indices"; # directory where the indices are
104 > $gConfigDir = "/etc/debbugs"; # directory where this file is
105 > $gSpoolDir = "/home/opw/spool"; # working directory
106 > $gIndicesDir = "/home/opw/spool/indices"; # directory where the indices are
109 < $gWebDir = "/org/bugs.debian.org/www"; # base location of web pages
110 < $gDocDir = "/org/ftp.debian.org/ftp/doc"; # location of text doc files
112 > $gWebDir = "/home/opw/debbugs/html"; # base location of web pages
113 > $gDocDir = "/home/opw/debbugs/doc"; # location of text doc files
115 6. Configure Webserver
117 1. Copy example apache config
119 sudo cp $HOME/debbugs/examples/apache.conf /etc/apache2/sites-available/debbugs.conf
121 2. Update the directory entries and the following variables
126 < DocumentRoot /var/lib/debbugs/www/
128 > DocumentRoot /home/opw/debbugs/html/
130 < <Directory /var/lib/debbugs/www>
132 > <Directory /home/opw/debbugs/html>
134 < ScriptAlias /cgi-bin/ /var/lib/debbugs/www/cgi/
135 < <Directory "/var/lib/debbugs/www/cgi/">
137 > ScriptAlias /cgi-bin/ /home/opw/debbugs/cgi/
138 > <Directory "/home/opw/debbugs/cgi/">
140 3. Enable required apache mods
147 sudo a2ensite debbugs
149 7. Install dependencies
151 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
155 1. Create symlinks to link source to their expected locations
157 sudo mkdir -p /usr/local/lib/site_perl
158 sudo ln -s /home/opw/debbugs/Debbugs /usr/local/lib/site_perl/
160 sudo mkdir -p /usr/share/debbugs/
161 sudo ln -s /home/opw/debbugs/templates /usr/share/debbugs/
163 9. Create required files
167 touch /etc/debbugs/pseudo-packages.description
168 touch /etc/debbugs/Source_maintainers
169 touch /etc/debbugs/pseudo-packages.maintainers
170 touch /etc/debbugs/Maintainers
171 touch /etc/debbugs/Maintainers.override
172 mkdir /etc/debbugs/indices
173 touch /etc/debbugs/indices/sources
178 perl -c cgi/bugreport.cgi
179 REQUEST_METHOD=GET QUERY_STRING="bug=775300" perl cgi/bugreport.cgi;
181 10. Install MTA. See README.mail for details.
183 Note that each line of `/etc/debbugs/Maintainers` file needs to be formatted as
186 package maintainer name <email@address>
188 If you need a template, look in `/usr/share/doc/debbugs/examples/` directory.
190 ### How do I contribute to Debbugs? ###
192 #### Debbugs for Debbugs ####
194 Debbugs bugs are tracked using Debbugs. The web interface is available:
195 [Debbugs bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?repeatmerged=no&src=debbugs)
197 #### Start contributing ####
199 Make a working branch for your code and check it out to start working:
201 git checkout -b example-branch
203 Stage and commit your changes using appropriate commit messages
207 git commit -m "Created an example file to demonstrate basic git commands."
209 #### Submitting a Patch ####
211 Submitting a patch can be done using git format-patch.
215 git format-patch origin/master
217 Creates `.patch` files for all commits since the branch diverged from master.
219 Debbugs bugs are tracked using debbugs (what else). Patches should therefore be
220 attached to the bug report for the issue. This can be done by emailing the
221 `.patch` files to `xxxx@bugs.debian.org` (where xxxx is the bug number).
223 Feature patches can also be emailed to the maintaining list at
224 [Debugs mailing list](debian-debbugs@lists.debian.org)
226 ### Further Information and Assistance ###
230 * Mailing List <debian-debbugs@lists.debian.org>
232 * To subscribe to the mailing list, email
233 <debian-debbugs-request@lists.debian.org> with the word "subscribe" in the
238 * [Code](https://bugs.debian.org/debbugs-source/debbugs.git/)
239 * [Debbugs Team](https://wiki.debian.org/Teams/Debbugs|Debbugs Team)
243 Join the #debbugs channel on [OFTC](irc.oftc.net)
247 This bug tracking system was developed by Ian Jackson from 1994-1997,
248 with assistance from nCipher Corporation Limited in 1997. nCipher allowed
249 Ian to redistribute modifications he made to the system while working as an
252 Since then, it has been developed by the various administrators of
253 bugs.debian.org, including Darren Benham, Adam Heath, Josip Rodin, Anthony
254 Towns, and Colin Watson. As in the case of Ian, nCipher allowed Colin to
255 redistribute modifications he made while working as an employee of nCipher.
257 ### Copyright and Lack-of-Warranty Notice ###
259 * Copyright 1999 Darren O. Benham
260 * Copyright 1994-1997 Ian Jackson
261 * Copyright 1997,2003 nCipher Corporation Limited
263 This bug system is free software; you can redistribute it and/or modify it
264 under the terms of the GNU General Public License as published by the Free
265 Software Foundation; version 2 of the License.
267 This program and documentation is distributed in the hope that it will be
268 useful, but without any warranty; without even the implied warranty of
269 merchantability or fitness for a particular purpose. See the GNU General
270 Public License for more details.
272 You should have received a copy of the GNU General Public License along
273 with this program, or one should be available above; if not, write to the
274 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA