html/Reporting.html.in

   1 $gReportingHtml = <<HTML_END
   2 <html><head><title>$gProject $gBugs - how to report a $gBug</title>
   3 <link rev="made" href="mailto:$gMaintainerEmail">
   4 </head><body>
   5 <h1>How to report a $gBug in $gProject</h1>
   6
   7 Send mail to
   8 <A href="mailto:submit\@$gEmailDomain"><code>submit\@$gEmailDomain</code></A>,
   9 as described below.
  10 <p>
  11
  12 Please don't report several unrelated $gBugs - especially ones in
  13 different packages - in one message.  Also, please don't mail your $gBug
  14 report to any mailing lists or recipients other than
  15 <code>submit\@$gEmailDomain</code> (for details of how to do this right, see
  16 <A href="#xcc">below</A>).
  17 <p>
  18
  19 Lists of currently-outstanding $gBugs are available <A href="./">on
  20 the World Wide Web</A> and <A href="Access.html">elsewhere</A> - see
  21 other documents for details.
  22 <p>
  23
  24 You should put a pseudo-header at the start of the body of the
  25 message, with the <code>Package:</code> and <code>Version:</code>
  26 lines giving the name and version of the package which has the $gBug.
  27 (The pseudo-header fields must start at the very start of their lines,
  28 and the $gBug system does not currently understand them if they're
  29 buried in MIMEd or PGPd mail.)
  30
  31 $gHTMLFindPackage
  32
  33 <em>See below for <A href="#details">further requirements</A></em>.
  34 <p>
  35
  36 $gHTMLPseudoDesc
  37
  38 <h2><A name="example">Example</A></h2>
  39
  40 A $gBug report, with mail header, looks something like this:
  41 <pre>
  42   To: submit\@$gEmailDomain
  43   From: diligent\@testing.linux.org
  44   Subject: Hello says `goodbye'
  45 <A name="psuedoheader">Package: hello</A>
  46   Version: 1.3-2
  47
  48   When I invoke `hello' without arguments from an ordinary shell
  49   prompt it prints `goodbye', rather than the expected `hello, world'.
  50   Here is a transcript:
  51
  52   $ hello
  53   goodbye
  54   $ /usr/bin/hello
  55   goodbye
  56   $
  57
  58   I suggest that the output string, in hello.c, be corrected.
  59
  60   I am using Debian 1.1, kernel version 1.3.99.15z
  61   and libc 5.2.18.3.2.1.3-beta.
  62 </pre>
  63
  64 <h2><A name="details">Please include in your report:</A></h2>
  65
  66 <ul>
  67 <li>The <em>exact</em> and <em>complete</em> text of any error
  68 messages printed or logged.  This is very important!
  69 <li>Exactly what you typed or did to demonstrate the problem.
  70 <li>A description of the incorrect behaviour: exactly what behaviour
  71 you were expecting, and what you observed.  A transcript of an
  72 example session is a good way of showing this.
  73 <li>A suggested fix, or even a patch, if you have one.
  74 <li>Details of the configuration of the program with the problem.
  75 Include the complete text of its configuration files.
  76 $gXtraBugInfo
  77 </ul>
  78
  79 Include any detail that seems relevant - you are in very little danger
  80 of making your report too long by including too much information.  If
  81 they are small please include in your report any files you were using
  82 to reproduce the problem (uuencoding them if they may contain odd
  83 characters etc.).
  84
  85 <p>
  86
  87 Of course, like any email, you should include a clear, descriptive
  88 <code>Subject</code> line in your main mail header.  The subject you
  89 give will be used as the initial $gBug title in the tracking system, so
  90 please try to make it informative !
  91
  92 <h2><A name="xcc">Sending copies of $gBug reports to other addresses</A></h2>
  93
  94 Sometimes it is necessary to send a copy of a $gBug report to somewhere
  95 else besides the mailing list and the package maintainer, which is where they
  96 are normally sent.
  97 <p>
  98
  99 You could do this by CC'ing your $gBug report to the other address(es),
 100 but then the other copies would not have the $gBug report number put in
 101 the <code>Reply-To</code> field and the <code>Subject</code> line.
 102 When the recipients reply they will probably preserve the
 103 <code>submit\@$gEmailDomain</code> entry in the header and have their
 104 message filed as a new $gBug report.  This leads to many duplicated
 105 reports.
 106 <p>
 107
 108 The <em>right</em> way to do this is to use the
 109 <code>X-$gProject-CC</code> header.  Add a line like this to your
 110 message's mail header (not to the psuedo header with the
 111 <code>Package</code> field):
 112 <pre>
 113  X-$gProject-CC: other-list\@cosmic.edu
 114 </pre>
 115 This will cause the $gBug tracking system to send a copy of your report
 116 to the address(es) in the <code>X-$gProject-CC</code> line as well as to
 117 any mailing list.
 118 <p>
 119
 120 This feature can often be combined usefully with mailing
 121 <code>quiet</code> - see below.
 122
 123
 124 <h2><A name="severities">Severity levels</A></h2>
 125
 126 If a report is of a particularly serious $gBug, or is merely a feature
 127 request that, you can set the severity level of the $gBug as you report
 128 it.  This is not required, however, and the developers will assign an
 129 appropriate severity level to your report if you do not.
 130 <p>
 131
 132 To assign a severity level put a
 133 <code>Severity: <var>severity</var></code> line in the psuedo-header,
 134 together with <code>Package</code> and <code>Version</code>.  The
 135 severity levels available are described in the
 136 <A href="Developer.html#severities">developers' documentation</A>.
 137
 138
 139 <h2>Not forwarding to the mailing list - minor $gBug reports</h2>
 140
 141 If a $gBug report is minor (for example, a documentation typo or other
 142 trivial build problem), or you're submitting many reports at once,
 143 send them to <code>maintonly\@$gEmailDomain</code> or <code>quiet\@$gEmailDomain</code>.
 144 <code>maintonly</code> will send the report on to the package
 145 maintainer (provided you supply a correct <code>Package</code> line in
 146 the pseudo-header and the maintainer is known), and <code>quiet</code>
 147 will not forward it anywhere at all but only file it as a $gBug (useful
 148 if, for example, you are submitting many similar $gBugs and want to post
 149 only a summary).
 150 <p>
 151
 152 If you do this the $gBug system will set the <code>Reply-To</code> of
 153 any forwarded message so that replies will by default be processed in
 154 the same way as the original report.
 155
 156 <h3>Unknown packages or $gBugs with no <code>Package</code> key</h3>
 157
 158 If the $gBug tracking system doesn't know who the maintainer of the
 159 relevant package is it'll forward the report to
 160 the mailing list even if <code>maintonly</code> was used.
 161 <p>
 162
 163 When sending to <code>maintonly\@$gEmailDomain</code> or
 164 <var>nnn</var><code>-maintonly\@$gEmailDomain</code> you should make sure that
 165 the $gBug report is assigned to the right package, by putting a correct
 166 <code>Package</code> at the top of an original submission of a report,
 167 or by using <A href="server-control.html">the
 168 <code>control\@$gEmailDomain</code> service</A> to (re)assign the report
 169 appropriately first if it isn't correct already.
 170
 171 $gXtraReportingInfo
 172
 173 <hr>
 174 Other pages:
 175 <ul>
 176 <li><A href="./">Bug tracking system main contents page.</A>
 177 <li><A href="Developer.html">Developers'
 178 information regarding the $gBug processing system.</A>
 179 <li><A href="Access.html">Accessing the $gBug tracking logs other than by WWW.</A>
 180 <li><A href="db/ix/full.html">Full list of outstanding and recent $gBug reports.</A>
 181 <li><A href="db/ix/packages.html">Packages with $gBug reports.</A>
 182 <li><A href="db/ix/maintainers.html">Maintainers of packages with $gBug reports.</A>
 183
 184 $gHTMLOtherPageList
 185
 186 </ul>
 187
 188 $gHTMLEnd
 189
 190 HTML_END