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