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.  Optional - Retrieve a partial database of bugs for testing
  56
  57     It's 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.  Optional - Retrieve bts-versions directory for testing purposes
  70
  71     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            as follows:
 100
 101                         70,72c70,72
 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
 105                         ---
 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
 109
 110                         74,75c74,75
 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
 113                         ---
 114                         > $gWebDir = "/path/to/directory/debbugs/html"; # base location of web pages
 115                         > $gDocDir = "/path/to/directory/debbugs/doc"; # location of text doc files
 116
 117 6.  Configure Webserver
 118
 119     1. Copy example apache config
 120
 121             sudo cp $HOME/debbugs/examples/apache.conf  /etc/apache2/sites-available/debbugs.conf
 122
 123     2. Update the directory entries and the DocumentRoot and ScriptAlias variables
 124
 125                     5c5
 126                     < DocumentRoot /var/lib/debbugs/www/
 127                         ---
 128                     > DocumentRoot /path/to/directory/debbugs/html/
 129
 130                     10c10
 131                     < <Directory /var/lib/debbugs/www>
 132                         ---
 133                     > <Directory /path/to/directory/debbugs/html>
 134
 135                     16,17c16,17
 136                     < ScriptAlias /cgi-bin/ /var/lib/debbugs/www/cgi/
 137                     < <Directory "/var/lib/debbugs/www/cgi/">
 138                         ---
 139                     > ScriptAlias /cgi-bin/ /path/to/directory/debbugs/cgi/
 140                     > <Directory "/path/to/directory/debbugs/cgi/">
 141
 142     3. Enable required apache mods
 143
 144             sudo a2enmod rewrite
 145             sudo a2enmod cgid
 146
 147     4. Install site
 148
 149             sudo a2ensite debbugs
 150
 151 7. Install dependencies
 152
 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
 154
 155 8. Set up libraries
 156
 157     1. Create symlinks to link source to their expected locations
 158
 159                         sudo mkdir -p /usr/local/lib/site_perl
 160                         sudo ln -s /path/to/directory/debbugs/Debbugs /usr/local/lib/site_perl/
 161
 162                         sudo mkdir -p /usr/share/debbugs/
 163                         sudo ln -s /path/to/directory/debbugs/templates /usr/share/debbugs/
 164
 165 9. Create required files
 166
 167     1. Create files
 168
 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
 176
 177     2. Test
 178
 179             cd $HOME/debbugs
 180             perl -c cgi/bugreport.cgi
 181             REQUEST_METHOD=GET QUERY_STRING="bug=775300" perl cgi/bugreport.cgi;
 182
 183 10. Install MTA. See README.mail for details.
 184
 185 Note that each line of `/etc/debbugs/Maintainers` file needs to be formatted as
 186 follows:
 187
 188     package    maintainer name <email@address>
 189
 190 If you need a template, look in `/usr/share/doc/debbugs/examples/` directory.
 191
 192 ### How do I contribute to Debbugs? ###
 193
 194 #### Debbugs for Debbugs ####
 195
 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)
 198
 199 #### Start contributing ####
 200
 201 Make a working branch for your code and check it out to start working:
 202
 203     git checkout -b example-branch
 204
 205 Stage and commit your changes using appropriate commit messages
 206
 207     git add example-file
 208
 209     git commit -m "Created an example file to demonstrate basic git commands."
 210
 211 #### Submitting a Patch ####
 212
 213 Submitting a patch can be done using git format-patch.
 214
 215 For example
 216
 217     git format-patch origin/master
 218
 219 Creates `.patch` files for all commits since the branch diverged from master.
 220
 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).
 224
 225 Feature patches can also be emailed to the maintaining list at
 226 [Debugs mailing list](debian-debbugs@lists.debian.org)
 227
 228 ### Further Information and Assistance ###
 229
 230 #### Email ####
 231
 232 * Mailing List <debian-debbugs@lists.debian.org>
 233
 234 * To subscribe to the mailing list, email
 235   <debian-debbugs-request@lists.debian.org> with the word "subscribe" in the
 236   subject line.
 237
 238 #### Website ####
 239
 240    * [Code](https://bugs.debian.org/debbugs-source/debbugs.git/)
 241    * [Debbugs Team](https://wiki.debian.org/Teams/Debbugs|Debbugs Team)
 242
 243 #### IRC ####
 244
 245 Join the #debbugs channel on [OFTC](irc.oftc.net)
 246
 247 ### Developers ###
 248
 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
 252 employee of nCipher.
 253
 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.
 258
 259 ### Copyright and Lack-of-Warranty Notice ###
 260
 261  * Copyright 1999 Darren O. Benham
 262  * Copyright 1994-1997 Ian Jackson
 263  * Copyright 1997,2003 nCipher Corporation Limited
 264
 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.
 268
 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.
 273
 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
 277 02111-1307, USA.