<html> <head> <title>Patch Submission</title> </head> <body> <div id="apphead"> <h1><small>scons</small><br />Patch Submission</h1> </div> <p> <strong>You must now <a href="http://www.tigris.org/servlets/Login">log in</a> to a <a href="http://www.tigris.org">tigris.org</a> account before submitting a patch!</strong> </p> <p> Patches should be submitted to the <a href="http://scons.tigris.org/issues/enter_bug.cgi?component=scons&subcomponent=scons&issue_type=PATCH">"Enter Issue" page</a>. Please follow the <a href="patch-submission.html#guidelines">submission guidelines</a> below to make sure your patch contains the necessary information. A more detailed set of <a href="patch-submission.html#steps">submission steps</a> can be found below. </p> </div> <div class="h2 app" style="border-left: 0px" id="customcontent"> <h2 id="guidelines">Guidelines for Patch Submission</h2> <p> To try to maintain and improve the quality of SCons releases, we have some pretty high standards for the quality of patches that make it into the SCons code base. This list of guidelines describes how to make it as easy as possible for your patch to be accepted for integration. We're still interested in your code even if you don't follow all of these guidelines, but then your patch will more than likely sit in the queue until someone else has time to supply all of the necessary missing items. </p> <ul> <li> <strong> Please <a href="http://www.tigris.org/servlets/Login">log in</a> to your tigris.org account before submitting any patch </strong> <p> If you do not already have a tigris.org account, register for one at <a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>. </p> <p> We no longer accept anonymous patches, due to spambot abuse of the open-door policy. </p> </li> <li> <strong>If your patch is extensive, discuss it first on the <a href="mailto:dev@scons.tigris.org">dev@scons.tigris.org</a> mailing list </strong> <p> In fact, for extensive changes, it's a good idea to have this discusssion <em>before</em> you invest too much time in coding. It's possible that your idea overlaps with something else already in the works, or that your idea is unlikely to be accepted because it would conflict with planned directions for SCons. It's much better to find that out, or get advice on acceptable design choices. before you've spent a lot of time polishing code that will be rejected because it doesn't fit plans for the architecture. </p> </li> <li> <strong>It's better to submit multiple patches with separate bits of functionality than a big patch containing lots of changes</strong> <p> Big, intertwined sets of changes increase the chances of unintended side effects that could cause the entire patch to be rejected. If you submit separate functional changes in separate patches, those change that meet all the criteria can still be integrated even though other pieces might be held up for one reason or another. </p> </li> <li> <strong>Submit your patch in <tt>diff -u</tt> or <tt>diff -c</tt> format</strong> <p> In particular, do <em>not</em> submit whole source files, or <tt>diff</tt> output without any kind of context information. It's much more difficult to integrate whole source files or plain <tt>diff</tt> output with other changes to the SCons code base, especially other changes that might be integrated after you've submitted your patch. </p> </li> <li> <strong>Your patch must include test case(s) before it can be integrated!</strong> <p> THIS IS THE SINGLE MOST COMMON REASON FOR DELAYS IN INTEGRATING PATCHES AND THE SINGLE MOST IMPORTANT THING YOU CAN DO TO INCREASE THE CHANCES OF YOUR PATCH BEING INTEGRATED QUICKLY. </p> <p> The SCons development methodology requires that each change be accompanied by one or more new or modified test cases that get added to our extensive regression test suite. This is to make sure that the behavior added by your patch doesn't get inadvertently broken by other changes in the future. Patches that fix bugs should contain at least one test case that demonstrates the behavior being fixed by the patch. For example, if you're fixing a configuration that causes SCons to exit with an error and a stack trace, the test case should trigger that stack trace when run against the current code. Patches that add new features or enhancements should contain test cases that use the new behavior being added to SCons. </p> <p> You can do any of the following to supply test cases with your patch: </p> <ul> <li> <strong>Include actual new or modified SCons test scripts in your patch</strong> <p> This is the best option because it's the easiest to integrate, and therefore maximizes the chances of your patch being accepted quickly. (Note that, yes, there's a curve to learning how to write test scripts in the SCons testing harness. We're working on documentation to deal with that.) </p> </li> <li> <strong>Include a .tar.gz or .zip file containing test configurations</strong> <p> If you can't quite figure out how to deal with the SCons test scripts, the next best option is to include with your patch an archive file containing one or more actual test configurations (<tt>SConscript</tt> files, input files, etc.). It will be relatively straightforward for someone integrating your patch, and who's presumably familiar with the SCons testing harness, to turn this into an appropriate test script. Be sure to include a description of how to run your recommended test scenario, or a script for doing so. </p> </li> <li> <strong>Describe how to go about testing the patch</strong> <p> If you really can't cook up a test configuration to include with the patch, the lowest-common-denominator approach is to just describe how to go about testing the patch. Be as specific as possible, even if you think it should be obvious how to test the patch. It might be clear to you while you're writing the code, but it will still take someone else time to make sure they understand your intent and work out the details of how to set up an appropriate case. The point is you're trying to use your existing knowledge of the bug being fixed or new feature being added to make the process of integrating your patch as simple and quick as possible, thereby increasing the chance of your patch making it into the SCons code base. </p> </li> </ul> <p> If you don't supply <em>any</em> sort of testing information with your patch, well, you're still welcome to submit the code. Just be aware that the patch will likely stay in the queue until someone has time to reverse-engineer a test case. </p> </li> <li> <strong>Your patch should not break any existing tests</strong> <p> This almost sounds like it should go without saying, but the reason we put so much emphasis on test cases is so that we can make sure functionality doesn't break. Your patch will almost certainly be run through the the complete set of checked-in test scripts, and if any of them break, your patch will either be rejected outright or delayed while someone else figures out how to fix it (or the tests) so that everything works correctly. You should, of course, avoid this by running your patch against the regression tests and fixing any problems <em>before</em> submitting your patch. If you run your patch against against the regression tests but can't figure out how to fix all the cases, the best bet would be to ask the <a href="mailto:dev@scons.tigris.org">dev@scons.tigris.org</a> mailing list. </p> </li> <li> <strong>Your patch should include documentation changes</strong> <p> We also insist that changes to the SCons code base be accompanied by appropriate changes to the documentation. In practice, right now we make sure the man page is up to date, and updates to the User's Guide often lag. </p> <p> Similar to the guidelines above for testing, if you don't submit changes to the actual man page with your patch, it's helpful if you at least provide some suggested text describing your change. Even if the actual words get rewritten (usually to make the style consistent with the rest of the man page), taking the time to provide this makes the integration easier because the person integrating the patch doesn't have to reverse-engineer the <em>intent</em> of your change to figure out how to describe it. </p> </li> </ul> <h2 id="steps">Steps for Submitting a Patch</h2> <p> The following guides you step-by-step through the process of submitting a patch to SCons. </p> <p> NOTE: Attaching a file or files (such as a .tar.gz or .zip file containing your patch) is a two-step process in the tigris.org Issue Tracker. You must first create the patch issue in the Tracker, and then attach the file(s) in a separate step, as described below. </p> <ul> <li> <strong><a href="http://www.tigris.org/servlets/Login">Log in</a> at tigris.org</strong> <p> If you do not already have a tigris.org account, register for one at <a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>. </p> <p> We no longer accept anonymous bug reports, due to spambot abuse of the open-door policy. </p> </li> <li> <strong>Go to the <a href="http://scons.tigris.org/issues/enter_bug.cgi?component=scons&subcomponent=scons&issue_type=PATCH">"Enter issue" page</a> </strong> <p> By default, the "scons" subcomponent is selected; if this bug is for a different subcomponent, select that instead. </p> </li> <li> <strong>Specify the version of SCons that you used as a baseline</strong> <p> You can leave this <tt>-unspecified-</tt>, in which case the assumption will be that you started with the code checked in to our Subversion repository at the time you opened the issue. </p> </li> <li> <strong>Fill in a good Summary line describing the patch</strong> <p> This line is what shows up in summary reports, so it should be descriptive but not too long. Avoid overly-general things like "SCons error," etc. </p> </li> <li> <strong>Fill in the Description field</strong> <p> This is where you should describe the nature of your patch: the exact error it fixes, the feature that it adds, how to go about testing it, etc. When in doubt, include more information rather than less. </p> </li> <li> <strong>Press the "Submit issue" to submit your report</strong> <p> You will now receive a <tt>Posting issue</tt> page that gives you the number of the issue you submitted. </p> </li> <li> <strong>Click the "Attach a file to this issue" link</strong> <p> </p> </li> <li> <strong>Fill in the "File" field with the path to the patch file you want to upload</strong> <p> (You can also do this through the <tt>Browse...</tt> button.) </p> </li> <li> <strong>Fill in the Description field</strong> <p> </p> </li> <li> <strong>Click the "Submit" button to attach your patch file</strong> <p> </p> </li> </ul> </div> </body> </html>