www/bug-submission.html

   1 <html>
   2 <head>
   3 <title>Bug Submission</title>
   4 </head>
   5 <body>
   6
   7 <div id="apphead">
   8 <h1><small>scons</small><br />Bug Submission</h1>
   9
  10 <p>
  11 <strong>You must now
  12 <a href="http://www.tigris.org/servlets/Login">log in</a>
  13 to a <a href="http://www.tigris.org">tigris.org</a> account
  14 before submitting a new bug report!</strong>
  15 </p>
  16
  17 <p>
  18 Bugs should be reported at the
  19 <a href="http://scons.tigris.org/issues/enter_bug.cgi?component=scons&subcomponent=scons&issue_type=DEFECT">"Enter Issue" page</a>.
  20 Please follow the <a href="bug-submission.html#guidelines">submission guidelines</a> below
  21 to make sure your bug report contains the necessary information.
  22 A more detailed set of <a href="bug-submission.html#steps">submission steps</a>
  23 can be found below.
  24 </p>
  25
  26 <p>
  27 The above URL is set up for reporting a bug in SCons itself.
  28 If you are reporting a problem in some other aspect of the SCons Project
  29 (such as the documentation, or any of the web pages),
  30 you must change the Subcomponent field of the submission form
  31 to some other appropriate value.
  32 </p>
  33
  34 </div>
  35
  36 <div class="h2 app" style="border-left: 0px" id="customcontent">
  37
  38 <h2 id="guidelines">Guidelines for a Useful Bug Report</h2>
  39
  40 <p>
  41 Your bug will be much more likely to get diagnosed and fixed
  42 if you supply all the necessary information to make it easy to do so.
  43 </p>
  44
  45 <ul>
  46 <li>
  47 <strong>
  48 <a href="http://www.tigris.org/servlets/Login">Log in</a>
  49 to your tigris.org account before submitting a bug report
  50 </strong>
  51 <p>
  52 If you do not already have a tigris.org account,
  53 register for one at
  54 <a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>.
  55 </p>
  56 <p>
  57 We no longer accept anonymous bug reports,
  58 due to spambot abuse of the open-door policy.
  59 </p>
  60 </li>
  61 <li>
  62 <strong>Specify the version of SCons in which you observed the problem</strong>
  63 <p>
  64 This helps avoid wasted time trying to pinpoint the version,
  65 and also allows us to confirm if a later released version
  66 has already fixed your problem.
  67 </p>
  68 </li>
  69 <li>
  70 <strong>Provide SConscript files or other configuration that reproduce the problem</strong>
  71 <p>
  72 If you can, simplify the configuration to just the
  73 minimal subset that demonstrates the problem.
  74 It's much harder to diagnose a problem
  75 if the incorrect behavor is due to
  76 one particular item out of a thousand
  77 in a large configuration.
  78 </p>
  79 <p>
  80 That said, it's most convenient if you can provide
  81 an actual configuration (set of SConscript files
  82 and/or other input files)
  83 that can be downloaded and run to demonstrate the bug.
  84 The easiest way is to attach a .tar.gz or .zip file
  85 to the bug report.
  86 Note that the tigris.org Issue Tracker
  87 doesn't let you attach a file like this
  88 when you initially submit the report.
  89 You must first create the bug report,
  90 and then attach a file to it as a separate step.
  91 See below for the detailed steps.
  92 </p>
  93 <p>
  94 If your problem is evident from a few specific SConscript lines,
  95 it's perfectly acceptable just to
  96 paste the lines into the Description field of the bug report.
  97 </p>
  98 </li>
  99 <li>
 100 <strong>Describe specifically the incorrect behavor you observed</strong>
 101 <p>
 102 It's best if you can cut and paste the output from SCons,
 103 especially any error messages.
 104 Otherwise,
 105 Vague descriptions like,
 106 "SCons errors out," or "Product XYZ doesn't compile"
 107 are extremely difficult to diagnose,
 108 because the different installed tools on someone else's system
 109 may cause SCons to behave differently
 110 and not demonstrate your bug.
 111 </p>
 112 </li>
 113 <li>
 114 <strong>Describe what you expected to happen</strong>
 115 <p>
 116 This isn't always obvious, especially if the
 117 bug does not involve an SCons failure or error message.
 118 Describing the behavior you expected
 119 helps speed up the diagnosis.
 120 </p>
 121 </li>
 122 </ul>
 123
 124 <h2 id="steps">Steps for Submitting a Bug Report</h2>
 125
 126 <p>
 127 The following guides you step-by-step through the
 128 process of submitting a new SCons bug report.
 129 </p>
 130
 131 <p>
 132 NOTE:  Creating a bug report with an attached file or files
 133 (such as a .tar.gz or .zip file containing a sample configuration)
 134 is a two-step process in the tigris.org Issue Tracker.
 135 You must first create the bug report,
 136 and then attach the file(s) in a separate step,
 137 as described below.
 138 </p>
 139
 140 <ul>
 141 <li>
 142 <strong><a href="http://www.tigris.org/servlets/Login">Log in</a> at tigris.org</strong>
 143 <p>
 144 If you do not already have a tigris.org account,
 145 register for one at
 146 <a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>.
 147 </p>
 148 <p>
 149 We no longer accept anonymous bug reports,
 150 due to spambot abuse of the open-door policy.
 151 </p>
 152 </li>
 153 <li>
 154 <strong>Go to the
 155 <a href="http://scons.tigris.org/issues/enter_bug.cgi?component=scons&subcomponent=scons&issue_type=DEFECT">"Enter issue" page</a>
 156 </strong>
 157 <p>
 158 By default, the "scons" subcomponent is selected;
 159 if this bug is for a different subcomponent, select that instead.
 160 </p>
 161 </li>
 162 <li>
 163 <strong>Specify the version of SCons in which you found the bug</strong>
 164 <p>
 165 </p>
 166 </li>
 167 <li>
 168 <strong>Specify the Subcomponent (if the bug is not in SCons itself)</strong>
 169 <p>
 170 The URL two steps above assumes that you're reporting
 171 a bug in the behavior of SCons itself.
 172 If you're reporting a problem in some other aspect of the SCons Project
 173 (such as the documentation, or the packaging),
 174 please change the Subcomponent field to reflect that.
 175 </p>
 176 </li>
 177 <li>
 178 <strong>Specify the Platform and OS</strong>
 179 <p>
 180 The Platform field is less important here
 181 (SCons doesn't have many behavioral difference
 182 due to different hardware platforms)
 183 but the OS field is important.
 184 </p>
 185 </li>
 186 <li>
 187 <strong>Fill in a good Summary line describing the bug</strong>
 188 <p>
 189 This line is what shows up in summary reports,
 190 so it should be descriptive but not too long.
 191 Avoid overly-general things like "SCons error," etc.
 192 </p>
 193 </li>
 194 <li>
 195 <strong>Fill in the Description field</strong>
 196 <p>
 197 This is where you should go into detail
 198 about the configuration,
 199 the exact error you see,
 200 what you expected to happen, etc.
 201 When in doubt, include more information rather than less.
 202 </p>
 203 </li>
 204 <li>
 205 <strong>Press the "Submit issue" to submit your report</strong>
 206 <p>
 207 You will now receive a <tt>Posting issue</tt> page
 208 that gives you the number of the issue you submitted.
 209 </p>
 210 </li>
 211 <li>
 212 <strong>If you have a .tar.gz, .zip or other file to attach:</strong>
 213 <ul>
 214 <li>
 215 <strong>Click the "Attach a file to this issue" link</strong>
 216 </li>
 217 <li>
 218 <strong>Fill in the "File" field with the path to the file you want to upload</strong>
 219 (You can also do this through the <tt>Browse...</tt> button.)
 220 </li>
 221 <li>
 222 <strong>Fill in the Description field</strong>
 223 </li>
 224 <li>
 225 <strong>Click the "Submit" button</strong>
 226 </li>
 227 </ul>
 228 </li>
 229 </ul>
 230
 231 </div>
 232
 233 </body>
 234 </html>