www/patch-submission.html

   1 <html>
   2 <head>
   3 <title>Patch Submission</title>
   4 </head>
   5 <body>
   6
   7 <div id="apphead">
   8 <h1><small>scons</small><br />Patch Submission</h1>
   9 </div>
  10
  11 <p>
  12 <strong>If you have not already done so, please
  13 <a href="http://www.tigris.org/servlets/Login">log in</a>
  14 before submitting a patch!</strong>
  15 <p>
  16
  17 <p>
  18 Patches should be submitted to
  19 <a href="http://scons.tigris.org/issues/enter_bug.cgi?subcomponent=scons&issue_type=PATCH">http://scons.tigris.org/issues/enter_bug.cgi?subcomponent=scons&issue_type=PATCH</a>
  20 Please follow the <a href="patch-submission.html#guidelines">submission guidelines</a> below
  21 to make sure your patch contains the necessary information.
  22 A more detailed set of <a href="patch-submission.html#steps">submission steps</a>
  23 can be found below.
  24 </p>
  25
  26 </div>
  27
  28 <div class="h2 app" style="border-left: 0px" id="customcontent">
  29
  30 <h2 id="guidelines">Guidelines for Patch Submission</h2>
  31
  32 <p>
  33 Your bug will be much more likely to get diagnosed and fixed
  34 if you supply all the necessary information to make it easy to do so.
  35 </p>
  36
  37 <ul>
  38
  39 <li>
  40 <strong>
  41 Please
  42 <a href="http://www.tigris.org/servlets/Login">log in</a>
  43 to your tigris.org account before submitting any patch
  44 </strong>
  45 <p>
  46 If you do not already have a tigris.org account,
  47 please register for one at
  48 <a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>.
  49 </p>
  50 <p>
  51 We do accept anonymous patches,
  52 but if the patch needs additional work or
  53 there are other questions about it,
  54 not knowing who submitted it
  55 will delay integration of the patch--or
  56 prevent it from being integrated at all.
  57 If you choose not to create a tigris.org account,
  58 at least put some identifying contact information
  59 in the bug description.
  60 </p>
  61 </li>
  62
  63 <li>
  64 <strong>If your patch is extensive, discuss it first on the
  65 <a href="mailto:dev@scons.tigris.org">dev@scons.tigris.org</a>
  66 mailing list
  67 </strong>
  68 <p>
  69 In fact, for extensive changes, it's a good idea to have this discusssion
  70 <emphasis>before</emphasis> you invest too much time in coding.
  71 It's possible that your idea would overlap with something else
  72 already in the works,
  73 or that your idea is unlikely to be accepted
  74 because it would conflict with planned directions for SCons.
  75 It's much better to find that out,
  76 or get advice on acceptable design choices.
  77 before you've spent a lot of time polishing code
  78 only to have it rejected.
  79 </p>
  80 </li>
  81
  82 <li>
  83 <strong>It's better to submit multiple patches with separate bits of functionality than a big patch containing lots of changes</strong>
  84 <p>
  85 Big, intertwined sets of changes
  86 increase the chances of unintended side effects
  87 that could case the entire patch to be rejected.
  88 If you submit separate functional changes in separate patches,
  89 change that meet all the criteria can
  90 still be integrated even
  91 though other pieces might held up for one reason or another.
  92 </p>
  93 </li>
  94
  95 <li>
  96 <strong>Submit your patch in <tt>diff -u</tt> or <tt>diff -c</tt> format</strong>
  97 <p>
  98 In particular, do <emphasis>not</emphasis> submit whole source files,
  99 or <tt>diff</tt> output without any kind of context information.
 100 It's much more difficult to integrate whole source files
 101 or plain <tt>diff</tt> output with other changes to
 102 the SCons code base.
 103 </p>
 104 </li>
 105
 106 <li>
 107 <strong>Your patch must include test caes before it can be integrated!</strong>
 108 <p>
 109 THIS IS THE SINGLE MOST COMMON REASON FOR DELAYS IN INTEGRATING PATCHES.
 110 </p>
 111 <p>
 112 The SCons development methodology requires
 113 that each change be accompanied by one or more test cases
 114 that get added to our extensive regression test suite,
 115 to make sure that the desired behavior added by the patch
 116 doesn't get inadvertently broken by other changes in the future.
 117 Patches that fix bugs should contain at least one test case
 118 that demonstrates the behavior being fixed by the patch--for
 119 example, if you're fixing a configuration that causes
 120 SCons to exit with an error and a stack trace,
 121 the test case should trigger that stack trace
 122 when run against the current code.
 123 Patches that add new features or enhancements
 124 should contain test cases that use
 125 the new behavior being added to SCons.
 126 </p>
 127 <p>
 128 You can do any of the following to supply
 129 test cases with your patch:
 130 </p>
 131 <ul>
 132 <li>
 133 <strong>Include actual new or modified SCons test scripts in your patch</strong>
 134 <p>
 135 This is the best option because it's the easiest to integrate.
 136 (Note that, yes, there's a curve to learning how to
 137 write test scripts in the SCons testing harness.
 138 We're working on documentation to deal with that.)
 139 </p>
 140 </li>
 141 <li>
 142 <strong>Include a .tar.gz or .zip file containing test configurations</strong>
 143 <p>
 144 If you can't quite figure out how to deal with the SCons test scripts,
 145 the next best option is to include with your patch an archive file
 146 containing one or more actual test configurations--<tt>SConscript</tt> files,
 147 input files, etc.
 148 It's relatively straightforard for someone who's familiar with the
 149 SCons testing harness to turn this into an appropriate test script.
 150 Be sure to include a description of how to run your test scenario,
 151 or a script for doing so.
 152 </p>
 153 </li>
 154 <li>
 155 <strong>Describe how to go about testing the patch</strong>
 156 <p>
 157 If you really can't cook up a test configuration to include with the patch,
 158 the lowest-common-denominator approach is to just describe
 159 how to go about testing the patch.
 160 Be as specific as possible,
 161 even if you think it should be obvious
 162 how to test the patch.
 163 It might be clear to you while you're writing the code,
 164 but it might still take someone else 15 minutes
 165 of making sure they understand the intent.
 166 The point is you're trying to use your knowledge
 167 to save time during the integration process,
 168 thereby increasing the chance of your patch making it
 169 into the SCons code base.
 170 </p>
 171 </li>
 172 </ul>
 173 <p>
 174 If you don't supply <emphasis>any</emphasis> sort of testing
 175 information with your patch,
 176 well, you're still welcome to submit the code.
 177 Just be aware that the patch will likely stay
 178 in the queue until someone has time to reverse-engineer
 179 a test cse.
 180 </p>
 181 </li>
 182
 183 <li>
 184 <strong>Your patch should not break any existing tests</strong>
 185 <p>
 186 This almost sounds like it should go without saying,
 187 but the reason we put so much emphasis on test cases
 188 is so that we can make sure functionality doesn't break.
 189 Your patch will almost certainly be run through the
 190 the complete set of checked-in test scripts,
 191 and if any of them break,
 192 your patch will either be rejected outright
 193 or delayed while someone else figures out how to
 194 You should, of course, avoid this by running your patch
 195 against the regression tests and fixing any problems
 196 <emphasis>before</emphasis> submitting your patch.
 197 If you run your patch against against the regression tests
 198 but can't figure out how to fix all the cases,
 199 the best bet would be to ask the
 200 <a href="mailto:dev@scons.tigris.org">dev@scons.tigris.org</a>
 201 mailing list.
 202 </p>
 203 </li>
 204
 205 <li>
 206 <strong>Your patch should include documentation changes</strong>
 207 <p>
 208 We also insist that changes to the SCons code base
 209 be accompanied by appropriate changes to the documentation.
 210 In practice, right now we make sure the man page is up to date,
 211 and updates to the User's Guide often lag.
 212 </p>
 213 <p>
 214 Similar to the guidelines above for testing,
 215 if you don't submit changes to the actual man page with your patch,
 216 it's helpful if you at least provide
 217 some suggested text describing your change.
 218 Even if the actual words get rewritten
 219 (usually to make the style consistent with the rest of the man page),
 220 taking the time to provide this
 221 makes the integration easier because
 222 the person integrating the patch doesn't have
 223 to reverse-engineer the <emphasis>intent</emphasis>
 224 of your change to figure out how to describe.
 225 </p>
 226 </li>
 227
 228 </ul>
 229
 230 <h2 id="steps">Steps for Submitting a Patch</h2>
 231
 232 <p>
 233 The following guides you step-by-step through the
 234 process of submitting a patch to SCons.
 235 </p>
 236
 237 <p>
 238 NOTE:  Attaching a file or files
 239 (such as a .tar.gz or .zip file containing your patch)
 240 is a two-step process in the tigris.org Issue Tracker.
 241 You must first create the patch issue in the Tracker,
 242 and then attach the file(s) in a separate step,
 243 as described below.
 244 </p>
 245
 246 <ul>
 247
 248 <li>
 249 <strong><a href="http://www.tigris.org/servlets/Login">Log in</a> at tigris.org</strong>
 250 <p>
 251 If you do not already have a tigris.org account,
 252 you can register for one at
 253 <a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>.
 254 </p>
 255 <p>
 256 You can still submit a patch anonymously, without logging in,
 257 but it may be impossible to integrate your patch
 258 if we need more information and have no
 259 idea who submitted the bug or how to contact you.
 260 If you choose not to create a tigris.org account,
 261 at least put some identifying contact information
 262 in the description.
 263 </p>
 264 </li>
 265
 266 <li>
 267 <strong>Go to the "Enter issue" page at
 268 <a href="http://scons.tigris.org/issues/enter_bug.cgi?subcomponent=scons&issue_type=PATCH">http://scons.tigris.org/issues/enter_bug.cgi?subcomponent=scons&issue_type=PATCH</a>
 269 </strong>
 270 <p>
 271 </p>
 272 </li>
 273
 274 <li>
 275 <strong>Specify the version of SCons that you used as a baseline</strong>
 276 <p>
 277 You can leave this <strong>-unspecified-</strong>,
 278 in which case the assumption will be that you started with
 279 the code checked in to our Subversion repository
 280 at the time you opened the issue.
 281 </p>
 282 </li>
 283
 284 <li>
 285 <strong>Fill in a good Summary line describing the patch</strong>
 286 <p>
 287 This line is what shows up in summary reports,
 288 so it should be descriptive but not too long.
 289 Avoid overly-general things like "SCons error," etc.
 290 </p>
 291 </li>
 292
 293 <li>
 294 <strong>Fill in the Description field</strong>
 295 <p>
 296 This is where you should go into detail
 297 about the configuration,
 298 the exact error you see,
 299 what you expected to happen, etc.
 300 When in doubt, include more information rather than less.
 301 </p>
 302 </li>
 303
 304 <li>
 305 <strong>Press the "Submit issue" to submit your report</strong>
 306 <p>
 307 You will now receive a <strong>Posting issue</strong> page
 308 that gives you the number of the issue you submitted.
 309 </p>
 310 </li>
 311
 312 <li>
 313 <strong>Click the "Attach a file to this issue" link</strong>
 314 <p>
 315 </p>
 316 </li>
 317
 318 <li>
 319 <strong>Fill in the "File" field with the path to the file you want to upload</strong>
 320 <p>
 321 (You can also do this through the <strong>Browse...</strong> button.)
 322 </p>
 323 </li>
 324
 325 <li>
 326 <strong>Fill in the Description field</strong>
 327 <p>
 328 </p>
 329 </li>
 330
 331 <li>
 332 <strong>Click the "Submit" button to attach your file</strong>
 333 <p>
 334 </p>
 335 </li>
 336
 337 </ul>
 338
 339 </div>
 340
 341 </body>
 342 </html>