README.md

   1 # Debbugs #
   2
   3 ## Debian Bug-Tracking System ##
   4
   5 ********************************
   6
   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.
   9
  10 The most notable deployment of Debbugs is on the [Debian project](https://www.debian.org/Bugs/)
  11
  12 ### System Requirements ###
  13
  14  * GNU date
  15  * GNU gzip
  16  * Perl 5 (5.005 is known to work)
  17  * Mailtools and MIME-tools perl modules to manipulate email
  18  * Lynx 2.7 or later
  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
  21    domain to a script.
  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).
  28
  29 ### Where do I get the Source? ###
  30
  31 Debbugs is managed in git. You can clone the repository into your local
  32 workspace as follows:
  33
  34     git clone http://bugs-master.debian.org/debbugs-source/debbugs.git
  35
  36 Additional branches are available from:
  37
  38  * [Don Armstrong](http://git.donarmstrong.com/debbugs.git/)
  39
  40 ### Installation Instructions ###
  41
  42 Install the Debian package and read `/usr/share/doc/debbugs/README.Debian` file.
  43
  44 If you can't use the `.deb`, do the following:
  45
  46 1.  Clone the repo
  47
  48         git clone http://bugs-master.debian.org/debbugs-source/debbugs.git
  49
  50 2.  Create version and spool directory
  51
  52         cd
  53         mkdir version spool
  54
  55 3.  Retrieve a partial database of bugs for testing
  56
  57     Optional - It is useful to have some bugs in the database for testing our new Debbugs instance.
  58
  59     1. Get a list of rsync targets from Debbugs
  60
  61            rsync --list-only rsync://bugs-mirror.debian.org
  62
  63     2. Grab bugs ending in 00
  64
  65            mkdir -p splool/db-h/00;
  66            cd spool/db-h;
  67            rsync -av rsync://bugs-mirror.debian.org/bts-spool-db/00 .;
  68
  69 4.  Retrieve bts-versions directory for testing purposes
  70
  71     Optional - Required for testing using test database retrieved at 3.
  72
  73     1. Pull versions directory
  74
  75            cd
  76            rsync -av rsync://bugs-mirror.debian.org/bts-versions/ versions/
  77
  78     2. Pull index directory
  79
  80            rsync -av rsync://bugs-mirror.debian.org/bts-spool-index index
  81
  82 5.  Configure Debbugs config
  83
  84     1. Create a config directory for Debbugs
  85
  86            sudo mkdir /etc/debbugs
  87
  88     2. Copy sample configuration to config directory
  89
  90            sudo cp ~/debbugs/scripts/config.debian /etc/debbugs/config
  91
  92     3. Update the following variables
  93        * $gConfigDir
  94        * $gSpoolDir
  95        * $gIndicesDir
  96        * $gWebDir
  97        * $gDocDir
  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 = "/home/opw/spool"; # working directory
 106              > $gIndicesDir = "/home/opw/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 = "/home/opw/debbugs/html"; # base location of web pages
 113              > $gDocDir = "/home/opw/debbugs/doc"; # location of text doc files
 114
 115 6.  Configure Webserver
 116
 117     1. Copy example apache config
 118
 119            sudo cp $HOME/debbugs/examples/apache.conf  /etc/apache2/sites-available/debbugs.conf
 120
 121     2. Update the directory entries and the following variables
 122        * DocumentRoot
 123        * ScriptAlias
 124
 125              5c5
 126              < DocumentRoot /var/lib/debbugs/www/
 127           ---
 128              > DocumentRoot /home/opw/debbugs/html/
 129              10c10
 130              < <Directory /var/lib/debbugs/www>
 131           ---
 132              > <Directory /home/opw/debbugs/html>
 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/ /home/opw/debbugs/cgi/
 138              > <Directory "/home/opw/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 7. Install dependencies
 150
 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
 152
 153 8. Set up libraries
 154
 155     1. Create symlinks to link source to their expected locations
 156
 157        sudo mkdir -p /usr/local/lib/site_perl
 158        sudo ln -s /home/opw/debbugs/Debbugs /usr/local/lib/site_perl/
 159
 160        sudo mkdir -p /usr/share/debbugs/
 161        sudo ln -s /home/opw/debbugs/templates /usr/share/debbugs/
 162
 163 9. Create required files
 164
 165     1. Create files
 166
 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
 174
 175     2. Test
 176
 177            cd $HOME/debbugs
 178            perl -c cgi/bugreport.cgi
 179            REQUEST_METHOD=GET QUERY_STRING="bug=775300" perl cgi/bugreport.cgi;
 180
 181 10. Install MTA. See README.mail for details.
 182
 183 Note that each line of `/etc/debbugs/Maintainers` file needs to be formatted as
 184 follows:
 185
 186     package    maintainer name <email@address>
 187
 188 If you need a template, look in `/usr/share/doc/debbugs/examples/` directory.
 189
 190 ### How do I contribute to Debbugs? ###
 191
 192 #### Debbugs for Debbugs ####
 193
 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)
 196
 197 #### Start contributing ####
 198
 199 Make a working branch for your code and check it out to start working:
 200
 201     git checkout -b example-branch
 202
 203 Stage and commit your changes using appropriate commit messages
 204
 205     git add example-file
 206
 207     git commit -m "Created an example file to demonstrate basic git commands."
 208
 209 #### Submitting a Patch ####
 210
 211 Submitting a patch can be done using git format-patch.
 212
 213 For example
 214
 215     git format-patch origin/master
 216
 217 Creates `.patch` files for all commits since the branch diverged from master.
 218
 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).
 222
 223 Feature patches can also be emailed to the maintaining list at
 224 [Debugs mailing list](debian-debbugs@lists.debian.org)
 225
 226 ### Further Information and Assistance ###
 227
 228 #### Email ####
 229
 230 * Mailing List <debian-debbugs@lists.debian.org>
 231
 232 * To subscribe to the mailing list, email
 233   <debian-debbugs-request@lists.debian.org> with the word "subscribe" in the
 234   subject line.
 235
 236 #### Website ####
 237
 238    * [Code](https://bugs.debian.org/debbugs-source/debbugs.git/)
 239    * [Debbugs Team](https://wiki.debian.org/Teams/Debbugs|Debbugs Team)
 240
 241 #### IRC ####
 242
 243 Join the #debbugs channel on [OFTC](irc.oftc.net)
 244
 245 ### Developers ###
 246
 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
 250 employee of nCipher.
 251
 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.
 256
 257 ### Copyright and Lack-of-Warranty Notice ###
 258
 259  * Copyright 1999 Darren O. Benham
 260  * Copyright 1994-1997 Ian Jackson
 261  * Copyright 1997,2003 nCipher Corporation Limited
 262
 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.
 266
 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.
 271
 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
 275 02111-1307, USA.