README

   1                      debbugs, Debian bug tracking system
   2                      -----------------------------------
   3
   4 This bug tracking system was developed by Ian Jackson from 1994-1997,
   5 with assistance from nCipher Corporation Limited in 1997.  nCipher allowed
   6 Ian to redistribute modifications he made to the system while working as an
   7 employee of nCipher.
   8
   9 Since then, it has been developed by the various administrators of
  10 bugs.debian.org, including Darren Benham, Adam Heath, Josip Rodin, Anthony
  11 Towns, and Colin Watson.  As in the case of Ian, nCipher allowed Colin to
  12 redistribute modifications he made while working as an employee of nCipher.
  13
  14 =============================================================================
  15 SYSTEM REQUIREMENTS
  16 =============================================================================
  17
  18  - GNU date
  19  - GNU gzip
  20  - Perl 5 (5.005 is known to work)
  21  - Mailtools and MIME-tools perl modules to manipulate email
  22  - Lynx 2.7 or later
  23  - The bug system requires its own mail domain.  It comes with code
  24    which understands how exim, qmail and sendmail deliver mail for such a
  25    domain to a script.
  26  - A webserver.  For the old system of static HTML pages generated for
  27    bug reports and index pages, this is easiest if the bug system can
  28    write directly to the webspace; for the new system of CGI scripts
  29    that generate web pages on the fly, write access is not required.
  30  - Somewhere to run CGI scripts (unless you don't need the web forms for
  31    searching for bugs by number, package, maintainer or submitter).
  32
  33 =============================================================================
  34 INSTALLATION INSTRUCTIONS
  35 =============================================================================
  36
  37 Install the Debian package and read /usr/share/doc/debbugs/README.Debian file.
  38
  39 If you can't use the .deb, do the following:
  40
  41 1. Run "make install" from the source directory.
  42
  43 2. Edit the config files in /etc/debbugs/ directory to suit your needs.
  44 Re-run debbugsconfig when you're finished to regenerate the
  45 documentation.
  46
  47 3. Set up the mail arrangements to deliver mail to the right place, and to
  48 set up a blackhole mail alias if you need one.  Ensure that owner@bugs, the
  49 address of the BTS owner, if that's what you're using, is handled by the MTA.
  50 All other email should be piped into the receive script.
  51
  52 4. Set up your HTTP server to point people looking for bug reports to
  53 /var/lib/debbugs/www and set /var/lib/debbugs/www/cgi as a valid CGI
  54 directory.
  55
  56 5. Test things a bit, by sending mail messages to the bug system and
  57 running /usr/lib/debbugs/processall and/or /usr/lib/debbugs/rebuild.
  58 The latter updates index files used by the CGI scripts.  If you're
  59 feeling brave, you can link /var/lib/debbugs/spool/index.db to
  60 index.db.realtime and .../index.archive to index.archive.realtime to
  61 remove the need for the rebuild script; this is still semi-experimental.
  62
  63 6. If all seems well then install the crontab from
  64 /usr/share/doc/debbugs/examples/crontab.
  65
  66 Notes:
  67
  68 Each line of /etc/debbugs/Maintainers file needs to be formatted like
  69 this: "package       maintainer name <e-mail@address>".
  70
  71 If you need a template, look in /usr/share/doc/debbugs/examples/ directory.
  72
  73 =============================================================================
  74 CONTRIBUTING TO DEBBUGS
  75 =============================================================================
  76
  77 Getting the Source Code
  78
  79 Debbugs is managed in git. You can clone the repository into your local workspace as follows:
  80
  81 git clone http://bugs-master.debian.org/debbugs-source/debbugs.git
  82
  83 Additional branches are available from:
  84
  85  * http://git.donarmstrong.com/debbugs.git/ (Maintainer: Don Armstrong)
  86
  87 Make a working branch for your code and check it out to start working:
  88
  89 git checkout -b example-branch
  90
  91 Stage and commit your changes using appropriate commit messages
  92
  93 git add example-file
  94
  95 git commit -m "Created an example file to demonstrate basic git commands."
  96
  97 Submitting a Patch
  98
  99 Submitting a patch can be done using git format-patch.
 100
 101 For example
 102
 103 git format-patch origin/master
 104
 105 Creates .patch files for all commits since the branch diverged from master.
 106
 107 Debbugs bugs are tracked using debbugs (what else). Patches should therefore be attached to the bug report for the issue. This can be done by emailing xxxx@bugs.debian.org (where xxxx is the bug number) with the patches attached. That's a terrible way of saying it, Stoopid.
 108
 109 Feature patches can also be emailed to the maintaining list at  debian-debbugs@lists.debian.org
 110
 111 =============================================================================
 112 FURTHER INFORMATION
 113 =============================================================================
 114
 115 Email: debian-debbugs@lists.debian.org (mailing list)
 116        To subscribe, email debian-debbugs-request@lists.debian.org
 117        with the word "subscribe" in the subject line
 118 Outdated web site: http://benham.net/debbugs/
 119
 120 =============================================================================
 121 COPYRIGHT AND LACK-OF-WARRANTY NOTICE
 122 =============================================================================
 123
 124 Copyright 1999 Darren O. Benham
 125 Copyright 1994-1997 Ian Jackson
 126 Copyright 1997,2003 nCipher Corporation Limited
 127
 128 This bug system is free software; you can redistribute it and/or modify it
 129 under the terms of the GNU General Public License as published by the Free
 130 Software Foundation; version 2 of the License.
 131
 132 This program and documentation is distributed in the hope that it will be
 133 useful, but without any warranty; without even the implied warranty of
 134 merchantability or fitness for a particular purpose. See the GNU General
 135 Public License for more details.
 136
 137 You should have received a copy of the GNU General Public License along
 138 with this program, or one should be available above; if not, write to the
 139 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 140 02111-1307, USA.