www/bug-submission.html

   1 <html>
   2 <head>
   3 <title>Bug Submission Guidelines</title>
   4 </head>
   5 <body>
   6
   7 <div id="apphead">
   8 <h1><small>scons</small><br />Bug Submission Guidelines</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="#guidelines">submission guidelines</a> below
  20 to make sure your bug report contains the necessary information.
  21 A more detailed set of <a href="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 </strong>
  69 <p>
  70 This helps avoid wasted time trying to pinpoint the version,
  71 and also allows us to confirm if a later released version
  72 has already fixed your problem.
  73 </p>
  74 </li>
  75 <li>
  76 <strong>Provide SConscript files or other configuration that reproduce the problem</strong>
  77 <p>
  78 If you can, simplify the configuration to just the
  79 minimal subset that demonstrates the problem.
  80 It's much harder to diagnose a problem
  81 if the incorrect behavor is due to
  82 one particular item out of a thousand
  83 in a large configuration.
  84 </p>
  85 <p>
  86 That said, it's most convenient if you can provide
  87 an actual configuration (set of SConscript files
  88 and/or other input files)
  89 that can be downloaded and run to demonstrate the bug.
  90 The easiest way is to attach a .tar.gz or .zip file
  91 to the bug report.
  92 Note that the tigris.org Issue Tracker
  93 doesn't let you attach a file like this
  94 when you initially submit the report.
  95 You must first create the bug report,
  96 and then attach a file to it as a separate step.
  97 See below for the detailed steps.
  98 </p>
  99 <p>
 100 If your problem is evident from a few specific
 101 SConscript files lines,
 102 it's perfectly acceptable just to
 103 paste the lines into the Description field of the bug report.
 104 </p>
 105 </li>
 106 <li>
 107 <strong>Describe specifically the incorrect behavor you observed</strong>
 108 <p>
 109 It's best if you can cut and paste the output from SCons,
 110 especially any error messages.
 111 Otherwise,
 112 Vague descriptions like,
 113 "SCons errors out," or "Product XYZ doesn't compile"
 114 are extremely difficult to diagnose,
 115 because the different installed tools on someone else's system
 116 may cause SCons to behave differently
 117 and not demonstrate your bug.
 118 </p>
 119 </li>
 120 <li>
 121 <strong>Describe what you expected to happen</strong>
 122 <p>
 123 This isn't always obvious, especially if the
 124 bug does not involve an SCons failure or error message.
 125 Describing the behavior you expected
 126 helps speed up the diagnosis.
 127 </p>
 128 </li>
 129 </ul>
 130
 131 <h2 id="steps">>Steps for Submitting a Bug Report</h2>
 132
 133 <p>
 134 The following guides you step-by-step through the
 135 process of submitting a new SCons bug report.
 136 </p>
 137
 138 <p>
 139 NOTE:  Creating a bug report with an attached file or files
 140 (such as a .tar.gz or .zip file containing a sample configuration)
 141 is a two-step process in the tigris.org Issue Tracker.
 142 You must first create the bug report,
 143 and then attach the file(s) in a separate step,
 144 as described below.
 145 </p>
 146
 147 <ul>
 148 <li>
 149 <strong>Log in at tigris.org</strong>
 150 <p>
 151 If you do not already have a tigris.org account,
 152 you can register for one at
 153 <a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>.
 154 </p>
 155 <p>
 156 You can still submit an anonymous bug report without logging in,
 157 but it may be impossible to diagnose or fix the bug
 158 if we need more information and have no
 159 idea who submitted the bug or how to contact you.
 160 If you choose not to create a tigris.org account,
 161 at least put some identifying contact information
 162 in the bug description.
 163 </p>
 164 </li>
 165 <li>
 166 <strong>Go to the "Enter issue" page at
 167 <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>
 168 </strong>
 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 <strong>If you have a .tar.gz, .zip or other file to attach:</strong>
 220 <li>
 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" with the path to the file you want to upload</strong>
 227 <p>
 228 You can also do this through the <strong>Browse...</strong> button.
 229 </p>
 230 </li>
 231 <li>
 232 <strong>Fill in the Description></strong>
 233 </li>
 234 <li>
 235 <strong>Click the "Submit" button</strong>
 236 </li>
 237 </ul>
 238 </li>
 239 </ul>
 240
 241 </div>
 242
 243 </body>
 244 </html>