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 ### Installation Instructions ###
  30
  31 Install the Debian package and read `/usr/share/doc/debbugs/README.Debian` file.
  32
  33 If you can't use the `.deb`, do the following:
  34
  35 1. Run `make install` from the source directory.
  36
  37 2. Edit the config files in `/etc/debbugs/` directory to suit your needs.
  38    Re-run debbugsconfig when you're finished to regenerate the documentation.
  39
  40 3. Set up the mail arrangements to deliver mail to the right place, and to set
  41    up a blackhole mail alias if you need one.  Ensure that `owner@bugs`, the
  42    address of the BTS owner, if that's what you're using, is handled by the MTA.
  43    All other email should be piped into the receive script.
  44
  45 4. Set up your HTTP server to point people looking for bug reports to
  46    `/var/lib/debbugs/www` and set `/var/lib/debbugs/www/cgi` as a valid CGI
  47    directory.
  48
  49 5. Test things a bit, by sending mail messages to the bug system and running
  50    `/usr/lib/debbugs/processall` and/or `/usr/lib/debbugs/rebuild`.  The latter
  51    updates index files used by the CGI scripts.  If you're feeling brave, you
  52    can link `/var/lib/debbugs/spool/index.db` to `index.db.realtime` and
  53    `.../index.archive` to `index.archive.realtime` to remove the need for the
  54    rebuild script; this is still semi-experimental.
  55
  56 6. If all seems well then install the crontab from
  57    `/usr/share/doc/debbugs/examples/crontab`.
  58
  59 Note that each line of `/etc/debbugs/Maintainers` file needs to be formatted as
  60 follows:
  61
  62     package    maintainer name <email@address>
  63
  64 If you need a template, look in `/usr/share/doc/debbugs/examples/` directory.
  65
  66 ### Where do I get the Source? ###
  67
  68 Debbugs is managed in git. You can clone the repository into your local
  69 workspace as follows:
  70
  71     git clone http://bugs-master.debian.org/debbugs-source/debbugs.git
  72
  73 Additional branches are available from:
  74
  75  * [Don Armstrong](http://git.donarmstrong.com/debbugs.git/)
  76
  77 ### How do I contribute to Debbugs? ###
  78
  79 #### Debbugs for Debbugs ####
  80
  81 Debbugs bugs are tracked using Debbugs. The web interface is available:
  82 [Debbugs bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?repeatmerged=no&src=debbugs)
  83
  84 #### Start contributing ####
  85
  86 Make a working branch for your code and check it out to start working:
  87
  88     git checkout -b example-branch
  89
  90 Stage and commit your changes using appropriate commit messages
  91
  92     git add example-file
  93
  94     git commit -m "Created an example file to demonstrate basic git commands."
  95
  96 #### Submitting a Patch ####
  97
  98 Submitting a patch can be done using git format-patch.
  99
 100 For example
 101
 102     git format-patch origin/master
 103
 104 Creates `.patch` files for all commits since the branch diverged from master.
 105
 106 Debbugs bugs are tracked using debbugs (what else). Patches should therefore be
 107 attached to the bug report for the issue. This can be done by emailing the
 108 `.patch` files to `xxxx@bugs.debian.org` (where xxxx is the bug number).
 109
 110 Feature patches can also be emailed to the maintaining list at
 111 [Debugs mailing list](debian-debbugs@lists.debian.org)
 112
 113 ### Further Information and Assistance ###
 114
 115 #### Email ####
 116
 117 * Mailing List <debian-debbugs@lists.debian.org>
 118
 119 * To subscribe to the mailing list, email
 120   <debian-debbugs-request@lists.debian.org> with the word "subscribe" in the
 121   subject line.
 122
 123 #### Website ####
 124
 125    * [Code](https://bugs.debian.org/debbugs-source/debbugs.git/)
 126    * [Debbugs Team](https://wiki.debian.org/Teams/Debbugs|Debbugs Team)
 127
 128 #### IRC ####
 129
 130 Join the #debbugs channel on [OFTC](irc.oftc.net)
 131
 132 ### Developers ###
 133
 134 This bug tracking system was developed by Ian Jackson from 1994-1997,
 135 with assistance from nCipher Corporation Limited in 1997. nCipher allowed
 136 Ian to redistribute modifications he made to the system while working as an
 137 employee of nCipher.
 138
 139 Since then, it has been developed by the various administrators of
 140 bugs.debian.org, including Darren Benham, Adam Heath, Josip Rodin, Anthony
 141 Towns, and Colin Watson. As in the case of Ian, nCipher allowed Colin to
 142 redistribute modifications he made while working as an employee of nCipher.
 143
 144 ### Copyright and Lack-of-Warranty Notice ###
 145
 146  * Copyright 1999 Darren O. Benham
 147  * Copyright 1994-1997 Ian Jackson
 148  * Copyright 1997,2003 nCipher Corporation Limited
 149
 150 This bug system is free software; you can redistribute it and/or modify it
 151 under the terms of the GNU General Public License as published by the Free
 152 Software Foundation; version 2 of the License.
 153
 154 This program and documentation is distributed in the hope that it will be
 155 useful, but without any warranty; without even the implied warranty of
 156 merchantability or fitness for a particular purpose. See the GNU General
 157 Public License for more details.
 158
 159 You should have received a copy of the GNU General Public License along
 160 with this program, or one should be available above; if not, write to the
 161 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 162 02111-1307, USA.