If you have not already done so, please log in before submitting a patch!
Patches should be submitted to http://scons.tigris.org/issues/enter_bug.cgi?subcomponent=scons&issue_type=PATCH Please follow the submission guidelines below to make sure your patch contains the necessary information. A more detailed set of submission steps can be found below.
Your bug will be much more likely to get diagnosed and fixed if you supply all the necessary information to make it easy to do so.
If you do not already have a tigris.org account, please register for one at http://www.tigris.org/servlets/Join.
We do accept anonymous patches, but if the patch needs additional work or there are other questions about it, not knowing who submitted it will delay integration of the patch--or prevent it from being integrated at all. If you choose not to create a tigris.org account, at least put some identifying contact information in the bug description.
In fact, for extensive changes, it's a good idea to have this discusssion
Big, intertwined sets of changes increase the chances of unintended side effects that could case the entire patch to be rejected. If you submit separate functional changes in separate patches, change that meet all the criteria can still be integrated even though other pieces might held up for one reason or another.
In particular, do
THIS IS THE SINGLE MOST COMMON REASON FOR DELAYS IN INTEGRATING PATCHES.
The SCons development methodology requires that each change be accompanied by one or more test cases that get added to our extensive regression test suite, to make sure that the desired behavior added by the 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.
You can do any of the following to supply test cases with your patch:
This is the best option because it's the easiest to integrate. (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.)
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--SConscript files, input files, etc. It's relatively straightforard for someone who's 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 test scenario, or a script for doing so.
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 might still take someone else 15 minutes of making sure they understand the intent. The point is you're trying to use your knowledge to save time during the integration process, thereby increasing the chance of your patch making it into the SCons code base.
If you don't supply
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
You should, of course, avoid this by running your patch
against the regression tests and fixing any problems
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.
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
The following guides you step-by-step through the process of submitting a patch to SCons.
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.
If you do not already have a tigris.org account, you can register for one at http://www.tigris.org/servlets/Join.
You can still submit a patch anonymously, without logging in, but it may be impossible to integrate your patch if we need more information and have no idea who submitted the bug or how to contact you. If you choose not to create a tigris.org account, at least put some identifying contact information in the description.
You can leave this -unspecified-, 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.
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.
This is where you should go into detail about the configuration, the exact error you see, what you expected to happen, etc. When in doubt, include more information rather than less.
You will now receive a Posting issue page that gives you the number of the issue you submitted.
(You can also do this through the Browse... button.)