Added contributing section

[debbugs.git] / README

diff --git a/README b/README
index 526f8d3637b337eb3bc9b8b52fa46384cb2d2853..c5a9a6596c99b9c41896e17c98d2ffabe8952dd1 100644 (file)
--- a/README
+++ b/README
@@ -1,122 +1,129 @@
-                     DEBIAN BUG TRACKING SYSTEM
-                     --------------------------
+                     debbugs, Debian bug tracking system
+                     -----------------------------------

 
 This bug tracking system was developed by Ian Jackson from 1994-1997,
 with assistance from nCipher Corporation Limited in 1997.  nCipher allowed
 Ian to redistribute modifications he made to the system while working as an
 employee of nCipher.
 
 
 This bug tracking system was developed by Ian Jackson from 1994-1997,
 with assistance from nCipher Corporation Limited in 1997.  nCipher allowed
 Ian to redistribute modifications he made to the system while working as an
 employee of nCipher.
 

+Since then, it has been developed by the various administrators of
+bugs.debian.org, including Darren Benham, Adam Heath, Josip Rodin, Anthony
+Towns, and Colin Watson.  As in the case of Ian, nCipher allowed Colin to
+redistribute modifications he made while working as an employee of nCipher.
+

 =============================================================================
 SYSTEM REQUIREMENTS
 =============================================================================
 =============================================================================
 SYSTEM REQUIREMENTS
 =============================================================================

- - GNU m4
+

  - GNU date
  - GNU gzip
  - GNU date
  - GNU gzip

- - Perl 5 (5.004 is known to work)
- - Mailtools perl module to manipulate email
+ - Perl 5 (5.005 is known to work)
+ - Mailtools and MIME-tools perl modules to manipulate email

  - Lynx 2.7 or later
  - The bug system requires its own mail domain.  It comes with code
    which understands how exim, qmail and sendmail deliver mail for such a 
    domain to a script.
  - Lynx 2.7 or later
  - The bug system requires its own mail domain.  It comes with code
    which understands how exim, qmail and sendmail deliver mail for such a 
    domain to a script.

- - A webserver (this is easiest if the bug system can write
-   directly to the webspace).
- - Somewhere to run CGI scripts (unless you don't need the `go to
-   bug' and `go to package' forms to work).
+ - A webserver.  For the old system of static HTML pages generated for
+   bug reports and index pages, this is easiest if the bug system can
+   write directly to the webspace; for the new system of CGI scripts
+   that generate web pages on the fly, write access is not required.
+ - Somewhere to run CGI scripts (unless you don't need the web forms for
+   searching for bugs by number, package, maintainer or submitter).

 
 =============================================================================
 INSTALLATION INSTRUCTIONS
 =============================================================================
 
 =============================================================================
 INSTALLATION INSTRUCTIONS
 =============================================================================

-1. Install the deb.  If you don't have a deb, consult the file list at the
-end of this document.

 
 

-2. Copy the template files from /usr/share/doc/debbugs/examples to
-/etc/debbugs.  Edit the config file, it is necessary.  Edit the text file if
-you wish to change some of the text as it gets displayed.
+Install the Debian package and read /usr/share/doc/debbugs/README.Debian file.
+
+If you can't use the .deb, do the following:
+
+1. Run "make install" from the source directory.
+
+2. Edit the config files in /etc/debbugs/ directory to suit your needs.
+Re-run debbugsconfig when you're finished to regenerate the
+documentation.
+
+3. Set up the mail arrangements to deliver mail to the right place, and to
+set up a blackhole mail alias if you need one.  Ensure that owner@bugs, the
+address of the BTS owner, if that's what you're using, is handled by the MTA.
+All other email should be piped into the receive script.
+
+4. Set up your HTTP server to point people looking for bug reports to
+/var/lib/debbugs/www and set /var/lib/debbugs/www/cgi as a valid CGI
+directory.

 
 

-3. Run "debbugsconfig"
+5. Test things a bit, by sending mail messages to the bug system and
+running /usr/lib/debbugs/processall and/or /usr/lib/debbugs/rebuild.
+The latter updates index files used by the CGI scripts.  If you're
+feeling brave, you can link /var/lib/debbugs/spool/index.db to
+index.db.realtime and .../index.archive to index.archive.realtime to
+remove the need for the rebuild script; this is still semi-experimental.

 
 

-4. Edit the /etc/debbugs/Maintainers file in the format of
-"package<whitespece>maintianer".
+6. If all seems well then install the crontab from
+/usr/share/doc/debbugs/examples/crontab.

 
 

-5. Set up the mail arrangements to deliver mail to the right place, and to
-set up a blackhole mail alias if you need one.  Ensure that owner@bugs, if
-that's what you're using, is handled by the MTA.
+Notes:

 
 

-6. Test things a bit, by sending mail messages to the bug system and
-running .../scripts/processall and/or .../scripts/update-html.
+Each line of /etc/debbugs/Maintainers file needs to be formatted like
+this: "package       maintainer name <e-mail@address>".

 
 

-7. If all seems well then install the crontab in `misc/crontab.out'.
+If you need a template, look in /usr/share/doc/debbugs/examples/ directory.

 
 =============================================================================
 
 =============================================================================

-FURTHER INFORMATION
+CONTRIBUTING TO DEBBUGS

 =============================================================================
 =============================================================================

-Web:  http://benham.net/debbugs/
-Email: debbugs@benham.net (mailing list)
-       debbugs-REQUEST@benham.net with the word subscribe in the body
+
+Getting the Source Code
+
+Debbugs is managed in git. You can clone the repository into your local workspace as follows:
+
+git clone http://bugs-master.debian.org/debbugs-source/debbugs.git
+
+Additional branches are available from:
+
+ * http://git.donarmstrong.com/debbugs.git/ (Maintainer: Don Armstrong)
+
+Make a working branch for your code and check it out to start working:
+
+git checkout -b example-branch
+
+Stage and commit your changes using appropriate commit messages
+
+git add example-file
+
+git commit -m "Created an example file to demonstrate basic git commands."
+
+Submitting a Patch
+
+Submitting a patch can be done using git format-patch.
+
+For example 
+
+git format-patch origin/master
+
+Creates .patch files for all commits since the branch diverged from master.
+
+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.
+ 
+Feature patches can also be emailed to the maintaining list at  debian-debbugs@lists.debian.org

 
 =============================================================================
 
 =============================================================================

-Filelist of installed files
+FURTHER INFORMATION

 =============================================================================
 =============================================================================

-********************config files**
--rw-r--r-- root/root      1293 1999-10-14 13:14:08 ./etc/debbugs/html/Access.html
--rw-r--r-- root/root      6983 1999-10-14 13:14:08 ./etc/debbugs/html/Reporting.html
--rw-r--r-- root/root      7460 1999-10-14 13:14:08 ./etc/debbugs/html/Developer.html
--rw-r--r-- root/root      3394 1999-10-14 13:14:08 ./etc/debbugs/html/index.html
--rw-r--r-- root/root      7608 1999-10-14 13:14:08 ./etc/debbugs/html/server-control.html
--rw-r--r-- root/root      6434 1999-10-14 13:14:08 ./etc/debbugs/html/server-request.html
--rw-r--r-- root/root      3579 1999-10-14 13:14:08 ./etc/debbugs/html/server-refcard.html
--rw-r--r-- root/root         2 1999-10-14 13:14:08 ./etc/debbugs/lynx-cfg
--rw-r--r-- root/root        79 1999-10-14 13:14:08 ./etc/debbugs/Maintainers
--rw-r--r-- root/root        59 1999-10-14 13:14:08 ./etc/debbugs/pseudo-packages.description
-********************scripts**
--rwxr-xr-x root/root       177 1999-10-14 13:14:07 ./usr/lib/debbugs/age-1
--rwxr-xr-x root/root     24471 1999-10-14 13:14:07 ./usr/lib/debbugs/db2html
--rwxr-xr-x root/root      2159 1999-10-14 13:14:07 ./usr/lib/debbugs/expire
--rwxr-xr-x root/root      3925 1999-10-14 13:14:07 ./usr/lib/debbugs/html-install
--rwxr-xr-x root/root      2747 1999-10-14 13:14:07 ./usr/lib/debbugs/mailsummary
--rwxr-xr-x root/root      1621 1999-10-14 13:14:07 ./usr/lib/debbugs/processall
--rwxr-xr-x root/root     25566 1999-10-14 13:14:08 ./usr/lib/debbugs/service
--rw-r--r-- root/root      2952 1999-10-14 13:14:08 ./usr/lib/debbugs/errorlib
--rwxr-xr-x root/root      3024 1999-10-14 13:14:08 ./usr/lib/debbugs/html-control
--rwxr-xr-x root/root     29290 1999-10-14 13:14:08 ./usr/lib/debbugs/process
--rwxr-xr-x root/root      3664 1999-10-14 13:14:08 ./usr/lib/debbugs/receive
--rwxr-xr-x root/root      3056 1999-10-14 13:14:08 ./usr/lib/debbugs/summary
-********************admin scripts*
--rwxr-xr-x root/root      1958 1999-10-14 13:14:08 ./usr/sbin/debbugsconfig
--rwxr-xr-x root/root       859 1999-10-14 13:14:08 ./usr/sbin/debbugs-maketxt
-********************documentation**
--rw-r--r-- root/root      2390 1999-10-14 13:14:08 ./usr/share/doc/debbugs/examples/config
--rw-r--r-- root/root     11146 1999-10-14 13:14:08 ./usr/share/doc/debbugs/examples/text
--rw-r--r-- root/root       432 1999-10-14 13:14:08 ./usr/share/doc/debbugs/examples/crontab
--rw-r--r-- root/root         3 1999-10-14 13:14:08 ./usr/share/doc/debbugs/examples/nextnumber
--rw-r--r-- root/root       321 1999-04-02 10:12:03 ./usr/share/doc/debbugs/TODO
--rw-r--r-- root/root      1430 1999-04-02 10:08:36 ./usr/share/doc/debbugs/README.Debian
--rw-r--r-- root/root       321 1999-04-02 10:12:03 ./usr/share/doc/debbugs/TODO.Debian
--rw-r--r-- root/root      1419 1999-03-27 11:26:38 ./usr/share/doc/debbugs/copyright
--rw-r--r-- root/root      1977 1999-04-16 17:21:00 ./usr/share/doc/debbugs/README.mail.gz
--rw-r--r-- root/root       812 1999-07-27 11:27:22 ./usr/share/doc/debbugs/changelog.Debian.gz
-********************web/data files
-drwxr-xr-x root/root         0 1999-10-14 13:14:08 ./var/lib/debbugs/www/cgi/
--rwxr-xr-x root/root      1807 1999-10-14 13:14:08 ./var/lib/debbugs/www/cgi/bugs-fetch2.pl
--rwxr-xr-x root/root      4755 1999-10-14 13:14:08 ./var/lib/debbugs/www/cgi/cgi-lib.pl
-drwxr-xr-x root/root         0 1999-10-14 13:14:08 ./var/lib/debbugs/www/db/
--rw-r--r-- root/root        37 1999-10-14 13:14:08 ./var/lib/debbugs/www/db/.htaccess
-drwxr-xr-x root/root         0 1999-10-14 13:14:07 ./var/lib/debbugs/www/txt/
--rw-r--r-- root/root        17 1999-10-14 13:14:08 ./var/lib/debbugs/spool/updateseqs
-********************needed, precreated directories
-drwxr-xr-x root/root         0 1999-10-14 13:14:07 ./var/lib/debbugs/indices/
-drwxr-xr-x root/root         0 1999-10-14 13:14:07 ./var/lib/debbugs/spool/lock/
-drwxr-xr-x root/root         0 1999-10-14 13:14:07 ./var/lib/debbugs/spool/archive/
-drwxr-xr-x root/root         0 1999-10-14 13:14:07 ./var/lib/debbugs/spool/incoming/
-drwxr-xr-x root/root         0 1999-10-14 13:14:07 ./var/lib/debbugs/spool/db/
+
+Email: debian-debbugs@lists.debian.org (mailing list)
+       To subscribe, email debian-debbugs-request@lists.debian.org
+       with the word "subscribe" in the subject line
+Outdated web site: http://benham.net/debbugs/

 
 =============================================================================
 COPYRIGHT AND LACK-OF-WARRANTY NOTICE
 =============================================================================
 
 =============================================================================
 COPYRIGHT AND LACK-OF-WARRANTY NOTICE
 =============================================================================

-Copyright 1999 Darren O. Benham <gecko@debian.org>
-Copyright 1994,1995,1996,1997 Ian Jackson <ijackson@chiark.greenend.org.uk>
-Copyright 1997 nCipher Corporation Limited
-Copyright 1995 Steven Brenner (for cgi-lib.pl).
+
+Copyright 1999 Darren O. Benham
+Copyright 1994-1997 Ian Jackson
+Copyright 1997,2003 nCipher Corporation Limited

 
 This bug system is free software; you can redistribute it and/or modify it
 under the terms of the GNU General Public License as published by the Free
 
 This bug system is free software; you can redistribute it and/or modify it
 under the terms of the GNU General Public License as published by the Free


@@ -131,5 +138,3 @@ You should have received a copy of the GNU General Public License along
 with this program, or one should be available above; if not, write to the
 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 02111-1307, USA.
 with this program, or one should be available above; if not, write to the
 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 02111-1307, USA.

-
- - gecko 14 Oct, 1999