]> git.donarmstrong.com Git - debbugs.git/blob - README.md
add cache_key support to binary_to_source when schema is set
[debbugs.git] / README.md
1 # Debbugs #
2
3 ## Debian Bug-Tracking System ##
4
5 ********************************
6
7 ### What is Debbugs? ###
8
9 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.
10
11 The most notable deployment of Debbugs is on the [Debian project](https://www.debian.org/Bugs/)
12
13 ### System Requirements ###
14
15  * GNU date
16  * GNU gzip
17  * Perl 5 (5.005 is known to work)
18  * Mailtools and MIME-tools perl modules to manipulate email
19  * Lynx 2.7 or later
20  * The bug system requires its own mail domain. It comes with code
21    which understands how exim, qmail and sendmail deliver mail for such a
22    domain to a script.
23  * A webserver. For the old system of static HTML pages generated for
24    bug reports and index pages, this is easiest if the bug system can
25    write directly to the webspace; for the new system of CGI scripts
26    that generate web pages on the fly, write access is not required.
27  * Somewhere to run CGI scripts (unless you don't need the web forms for
28    searching for bugs by number, package, maintainer or submitter).
29
30 ### Where do I get the Source? ###
31
32 Debbugs is managed in git. You can clone the repository into your local
33 workspace as follows:
34
35         git clone http://bugs-master.debian.org/debbugs-source/debbugs.git
36
37 Additional branches are available from:
38
39  * [Don Armstrong](http://git.donarmstrong.com/debbugs.git/)
40
41 ### Installation Instructions ###
42
43 Install the Debian package and read `/usr/share/doc/debbugs/README.Debian` file.
44
45 If you can't use the `.deb`, do the following:
46
47 1.  Clone the repo
48
49         git clone http://bugs-master.debian.org/debbugs-source/debbugs.git
50
51 2.  Create version and spool directory
52
53         cd
54         mkdir version spool
55
56 3.  Optional - Retrieve a partial database of bugs for testing
57
58     1. Get a list of rsync targets from Debbugs
59
60             rsync --list-only rsync://bugs-mirror.debian.org
61
62     2. Grab bugs ending in 00
63
64             mkdir -p splool/db-h/00;
65             cd spool/db-h;
66             rsync -av rsync://bugs-mirror.debian.org/bts-spool-db/00 .;
67
68 4.  Optional - Retrieve bts-versions directory for testing purposes
69
70     The database obtained in step 3 requires associated version and index information.
71
72     1. Pull versions directory
73
74             rsync -av rsync://bugs-mirror.debian.org/bts-versions/ versions/
75
76     2. Pull index directory
77
78             rsync -av rsync://bugs-mirror.debian.org/bts-spool-index index
79
80 5.  Configure Debbugs config
81
82     1. Create a config directory for Debbugs
83
84             sudo mkdir /etc/debbugs
85
86     2. Copy sample configuration to config directory
87
88             sudo cp ~/debbugs/scripts/config.debian /etc/debbugs/config
89
90     3. Update the following variables
91                 * $gConfigDir
92                 * $gSpoolDir
93                 * $gIndicesDir
94                 * $gWebDir
95                 * $gDocDir
96         
97            as follows:
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 = "/path/to/directory/spool"; # working directory
106                         > $gIndicesDir = "/path/to/directory/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 = "/path/to/directory/debbugs/html"; # base location of web pages
113                         > $gDocDir = "/path/to/directory/debbugs/doc"; # location of text doc files
114
115 6.  Configure Webserver
116
117     1. Copy example apache config
118
119             sudo cp /path/to/directory/debbugs/examples/apache.conf  /etc/apache2/sites-available/debbugs.conf
120
121     2. Update the directory entries and the DocumentRoot and ScriptAlias variables
122
123                     5c5
124                     < DocumentRoot /var/lib/debbugs/www/
125                         ---
126                     > DocumentRoot /path/to/directory/debbugs/html/
127                 
128                     10c10
129                     < <Directory /var/lib/debbugs/www>
130                         ---
131                     > <Directory /path/to/directory/debbugs/html>
132                 
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/ /path/to/directory/debbugs/cgi/
138                     > <Directory "/path/to/directory/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     5. Reload apache
150     
151                         sudo service apache2 reload
152             
153 7. Install dependencies
154
155         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
156        
157 8. Set up libraries
158    
159     1. Create symlinks to link source to their expected locations
160        
161                         sudo mkdir -p /usr/local/lib/site_perl
162                         sudo ln -s /path/to/directory/debbugs/Debbugs /usr/local/lib/site_perl/
163     
164                         sudo mkdir -p /usr/share/debbugs/
165                         sudo ln -s /path/to/directory/debbugs/templates /usr/share/debbugs/
166
167 9. Create required files
168        
169     1. Create files
170     
171             touch /etc/debbugs/pseudo-packages.description
172             touch /etc/debbugs/Source_maintainers
173             touch /etc/debbugs/pseudo-packages.maintainers
174             touch /etc/debbugs/Maintainers
175             touch /etc/debbugs/Maintainers.override
176             mkdir /etc/debbugs/indices
177             touch /etc/debbugs/indices/sources
178        
179     2. Test
180     
181             cd /path/to/directory/debbugs
182             perl -c cgi/bugreport.cgi
183             REQUEST_METHOD=GET QUERY_STRING="bug=775300" perl cgi/bugreport.cgi; 
184
185 10. Install MTA. See README.mail for details.
186
187 Note that each line of `/etc/debbugs/Maintainers` file needs to be formatted as
188 follows: 
189
190     package    maintainer name <email@address>
191
192 If you need a template, look in `/usr/share/doc/debbugs/examples/` directory.
193
194 ### How do I contribute to Debbugs? ###
195  
196 #### Debbugs bugs ####
197
198 Bugs in debbugs are tracked on the Debian bugtracker. The web interface is available at
199 [bugs.debian.org](https://bugs.debian.org/cgi-bin/pkgreport.cgi?repeatmerged=no&src=debbugs)
200
201 #### Start contributing ####
202
203 Make a working branch for your code and check it out to start working:
204
205         git checkout -b example-branch
206
207 Stage and commit your changes using appropriate commit messages
208
209         git add example-file
210
211         git commit -m "Created an example file to demonstrate basic git commands."
212
213 #### Submitting a Patch ####
214
215 Submitting a patch can be done using git format-patch.
216
217 For example
218
219         git format-patch origin/master
220
221 Creates `.patch` files for all commits since the branch diverged from master.
222
223 Debbugs bugs are tracked using debbugs (what else). Patches should therefore be
224 attached to the bug report for the issue. This can be done by emailing the
225 `.patch` files to `xxxx@bugs.debian.org` (where xxxx is the bug number).
226
227 Feature patches can also be emailed to the maintaining list at 
228 [Debugs mailing list](debian-debbugs@lists.debian.org)
229
230 ### Further Information and Assistance ###
231
232 #### Email ####
233
234 * Mailing List <debian-debbugs@lists.debian.org> 
235
236 * To subscribe to the mailing list, email
237   <debian-debbugs-request@lists.debian.org> with the word "subscribe" in the
238   subject line.
239
240 #### Website ####
241
242    * [Code](https://bugs.debian.org/debbugs-source/debbugs.git/)
243    * [Debbugs Team](https://wiki.debian.org/Teams/Debbugs)
244
245 #### IRC ####
246
247 Join the `#debbugs` channel on `irc.oftc.net`
248
249 ### Developers ###
250
251 This bug tracking system was developed by Ian Jackson from 1994-1997,
252 with assistance from nCipher Corporation Limited in 1997. nCipher allowed
253 Ian to redistribute modifications he made to the system while working as an
254 employee of nCipher.
255
256 Since then, it has been developed by the various administrators of
257 `bugs.debian.org`, including Darren Benham, Adam Heath, Josip Rodin, Anthony
258 Towns, and Colin Watson. As in the case of Ian, nCipher allowed Colin to
259 redistribute modifications he made while working as an employee of nCipher.
260
261 ### Copyright and Lack-of-Warranty Notice ###
262
263  * Copyright 1999 Darren O. Benham
264  * Copyright 1994-1997 Ian Jackson
265  * Copyright 1997,2003 nCipher Corporation Limited
266
267 This bug system is free software; you can redistribute it and/or modify it
268 under the terms of the GNU General Public License as published by the Free
269 Software Foundation; version 2 of the License.
270
271 This program and documentation is distributed in the hope that it will be
272 useful, but without any warranty; without even the implied warranty of
273 merchantability or fitness for a particular purpose. See the GNU General
274 Public License for more details.
275
276 You should have received a copy of the GNU General Public License along
277 with this program, or one should be available above; if not, write to the
278 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
279 02111-1307, USA.