README.md

   1 # Debbugs #
   2
   3 ## Debian Bug-Tracking System ##
   4
   5 ********************************
   6
   7 ### What is Debbugs? ###
   8
   9 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
  11 The most notable deployment of Debbugs is on the [Debian project](https://www.debian.org/Bugs/)
  12
  13 ### System Requirements ###
  14
  15  * GNU date
  16  * GNU gzip
  17  * Perl 5 (5.005 is known to work)
  18  * Mailtools and MIME-tools perl modules to manipulate email
  19  * Lynx 2.7 or later
  20  * The bug system requires its own mail domain. It comes with code
  21    which understands how exim, qmail and sendmail deliver mail for such a
  22    domain to a script.
  23  * A webserver. For the old system of static HTML pages generated for
  24    bug reports and index pages, this is easiest if the bug system can
  25    write directly to the webspace; for the new system of CGI scripts
  26    that generate web pages on the fly, write access is not required.
  27  * Somewhere to run CGI scripts (unless you don't need the web forms for
  28    searching for bugs by number, package, maintainer or submitter).
  29
  30 ### Where do I get the Source? ###
  31
  32 Debbugs is managed in git. You can clone the repository into your local
  33 workspace as follows:
  34
  35         git clone http://bugs-master.debian.org/debbugs-source/debbugs.git
  36
  37 Additional branches are available from:
  38
  39  * [Don Armstrong](http://git.donarmstrong.com/debbugs.git/)
  40
  41 ### Installation Instructions ###
  42
  43 Install the Debian package and read `/usr/share/doc/debbugs/README.Debian` file.
  44
  45 If you can't use the `.deb`, do the following:
  46
  47 1.  Clone the repo
  48
  49         git clone http://bugs-master.debian.org/debbugs-source/debbugs.git
  50
  51 2.  Create version and spool directory
  52
  53         cd
  54         mkdir version spool
  55
  56 3.  Optional - Retrieve a partial database of bugs for testing
  57
  58     1. Get a list of rsync targets from Debbugs
  59
  60             rsync --list-only rsync://bugs-mirror.debian.org
  61
  62     2. Grab bugs ending in 00
  63
  64             mkdir -p splool/db-h/00;
  65             cd spool/db-h;
  66             rsync -av rsync://bugs-mirror.debian.org/bts-spool-db/00 .;
  67
  68 4.  Optional - Retrieve bts-versions directory for testing purposes
  69
  70     The database obtained in step 3 requires associated version and index information.
  71
  72     1. Pull versions directory
  73
  74             rsync -av rsync://bugs-mirror.debian.org/bts-versions/ versions/
  75
  76     2. Pull index directory
  77
  78             rsync -av rsync://bugs-mirror.debian.org/bts-spool-index index
  79
  80 5.  Configure Debbugs config
  81
  82     1. Create a config directory for Debbugs
  83
  84             sudo mkdir /etc/debbugs
  85
  86     2. Copy sample configuration to config directory
  87
  88             sudo cp ~/debbugs/scripts/config.debian /etc/debbugs/config
  89
  90     3. Update the following variables
  91                 * $gConfigDir
  92                 * $gSpoolDir
  93                 * $gIndicesDir
  94                 * $gWebDir
  95                 * $gDocDir
  96
  97            as follows:
  98
  99                         70,72c70,72
 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
 103                         ---
 104                         > $gConfigDir = "/etc/debbugs"; # directory where this file is
 105                         > $gSpoolDir = "/path/to/directory/spool"; # working directory
 106                         > $gIndicesDir = "/path/to/directory/spool/indices"; # directory  where the indices are
 107
 108                         74,75c74,75
 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
 111                         ---
 112                         > $gWebDir = "/path/to/directory/debbugs/html"; # base location of web pages
 113                         > $gDocDir = "/path/to/directory/debbugs/doc"; # location of text doc files
 114
 115 6.  Configure Webserver
 116
 117     1. Copy example apache config
 118
 119             sudo cp /path/to/directory/debbugs/examples/apache.conf  /etc/apache2/sites-available/debbugs.conf
 120
 121     2. Update the directory entries and the DocumentRoot and ScriptAlias variables
 122
 123                     5c5
 124                     < DocumentRoot /var/lib/debbugs/www/
 125                         ---
 126                     > DocumentRoot /path/to/directory/debbugs/html/
 127
 128                     10c10
 129                     < <Directory /var/lib/debbugs/www>
 130                         ---
 131                     > <Directory /path/to/directory/debbugs/html>
 132
 133                     16,17c16,17
 134                     < ScriptAlias /cgi-bin/ /var/lib/debbugs/www/cgi/
 135                     < <Directory "/var/lib/debbugs/www/cgi/">
 136                         ---
 137                     > ScriptAlias /cgi-bin/ /path/to/directory/debbugs/cgi/
 138                     > <Directory "/path/to/directory/debbugs/cgi/">
 139
 140     3. Enable required apache mods
 141
 142             sudo a2enmod rewrite
 143             sudo a2enmod cgid
 144
 145     4. Install site
 146
 147             sudo a2ensite debbugs
 148
 149     5. Reload apache
 150
 151                         sudo service apache2 reload
 152
 153 7. Install dependencies
 154
 155         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
 156
 157 8. Set up libraries
 158
 159     1. Create symlinks to link source to their expected locations
 160
 161                         sudo mkdir -p /usr/local/lib/site_perl
 162                         sudo ln -s /path/to/directory/debbugs/Debbugs /usr/local/lib/site_perl/
 163
 164                         sudo mkdir -p /usr/share/debbugs/
 165                         sudo ln -s /path/to/directory/debbugs/templates /usr/share/debbugs/
 166
 167 9. Create required files
 168
 169     1. Create files
 170
 171             touch /etc/debbugs/pseudo-packages.description
 172             touch /etc/debbugs/Source_maintainers
 173             touch /etc/debbugs/pseudo-packages.maintainers
 174             touch /etc/debbugs/Maintainers
 175             touch /etc/debbugs/Maintainers.override
 176             mkdir /etc/debbugs/indices
 177             touch /etc/debbugs/indices/sources
 178
 179     2. Test
 180
 181             cd /path/to/directory/debbugs
 182             perl -c cgi/bugreport.cgi
 183             REQUEST_METHOD=GET QUERY_STRING="bug=775300" perl cgi/bugreport.cgi;
 184
 185 10. Install MTA. See README.mail for details.
 186
 187 Note that each line of `/etc/debbugs/Maintainers` file needs to be formatted as
 188 follows:
 189
 190     package    maintainer name <email@address>
 191
 192 If you need a template, look in `/usr/share/doc/debbugs/examples/` directory.
 193
 194 ### How do I contribute to Debbugs? ###
 195
 196 #### Debbugs bugs ####
 197
 198 Bugs in debbugs are tracked on the Debian bugtracker. The web interface is available at
 199 [bugs.debian.org](https://bugs.debian.org/cgi-bin/pkgreport.cgi?repeatmerged=no&src=debbugs)
 200
 201 #### Start contributing ####
 202
 203 Make a working branch for your code and check it out to start working:
 204
 205         git checkout -b example-branch
 206
 207 Stage and commit your changes using appropriate commit messages
 208
 209         git add example-file
 210
 211         git commit -m "Created an example file to demonstrate basic git commands."
 212
 213 #### Submitting a Patch ####
 214
 215 Submitting a patch can be done using git format-patch.
 216
 217 For example
 218
 219         git format-patch origin/master
 220
 221 Creates `.patch` files for all commits since the branch diverged from master.
 222
 223 Debbugs bugs are tracked using debbugs (what else). Patches should therefore be
 224 attached to the bug report for the issue. This can be done by emailing the
 225 `.patch` files to `xxxx@bugs.debian.org` (where xxxx is the bug number).
 226
 227 Feature patches can also be emailed to the maintaining list at
 228 [Debugs mailing list](debian-debbugs@lists.debian.org)
 229
 230 ### Further Information and Assistance ###
 231
 232 #### Email ####
 233
 234 * Mailing List <debian-debbugs@lists.debian.org>
 235
 236 * To subscribe to the mailing list, email
 237   <debian-debbugs-request@lists.debian.org> with the word "subscribe" in the
 238   subject line.
 239
 240 #### Website ####
 241
 242    * [Code](https://bugs.debian.org/debbugs-source/debbugs.git/)
 243    * [Debbugs Team](https://wiki.debian.org/Teams/Debbugs)
 244
 245 #### IRC ####
 246
 247 Join the `#debbugs` channel on `irc.oftc.net`
 248
 249 ### Developers ###
 250
 251 This bug tracking system was developed by Ian Jackson from 1994-1997,
 252 with assistance from nCipher Corporation Limited in 1997. nCipher allowed
 253 Ian to redistribute modifications he made to the system while working as an
 254 employee of nCipher.
 255
 256 Since then, it has been developed by the various administrators of
 257 `bugs.debian.org`, including Darren Benham, Adam Heath, Josip Rodin, Anthony
 258 Towns, and Colin Watson. As in the case of Ian, nCipher allowed Colin to
 259 redistribute modifications he made while working as an employee of nCipher.
 260
 261 ### Copyright and Lack-of-Warranty Notice ###
 262
 263  * Copyright 1999 Darren O. Benham
 264  * Copyright 1994-1997 Ian Jackson
 265  * Copyright 1997,2003 nCipher Corporation Limited
 266
 267 This bug system is free software; you can redistribute it and/or modify it
 268 under the terms of the GNU General Public License as published by the Free
 269 Software Foundation; version 2 of the License.
 270
 271 This program and documentation is distributed in the hope that it will be
 272 useful, but without any warranty; without even the implied warranty of
 273 merchantability or fitness for a particular purpose. See the GNU General
 274 Public License for more details.
 275
 276 You should have received a copy of the GNU General Public License along
 277 with this program, or one should be available above; if not, write to the
 278 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 279 02111-1307, USA.