scons
Bug Submission Guidelines

scons
Bug Submission

If you have not already done so, please @@ -65,7 +65,6 @@ in the bug description.

Specify the version of SCons in which you observed the problem -

This helps avoid wasted time trying to pinpoint the version, and also allows us to confirm if a later released version @@ -97,8 +96,7 @@ and then attach a file to it as a separate step. See below for the detailed steps.

-If your problem is evident from a few specific -SConscript files lines, +If your problem is evident from a few specific SConscript lines, it's perfectly acceptable just to paste the lines into the Description field of the bug report.

@@ -146,7 +144,7 @@ as described below.

-Log in at tigris.org +Log in at tigris.org
If you do not already have a tigris.org account, you can register for one at @@ -229,7 +227,7 @@ that gives you the number of the issue you submitted. (You can also do this through the Browse... button.)
-Fill in the Description fied +Fill in the Description field
Click the "Submit" button diff --git a/www/feature-request.html b/www/feature-request.html index 707379a2..a912ab6c 100644 --- a/www/feature-request.html +++ b/www/feature-request.html @@ -1,20 +1,87 @@ -Feature Request Guidelines +Feature Requests
-
scons
Feature Request Guidelines
+
scons
Feature Requests

-http://scons.tigris.org/issues/enter_bug.cgi?issue_type=FEATURE?subcomponent=scons +If you have not already done so, please +log in +before submitting a feature request! +
+ +
+Feature requests should be submitted to +http://scons.tigris.org/issues/enter_bug.cgi?subcomponent=scons&issue_type=FEATURE +A more detailed set of submission steps +can be found below. +
+ +

+ +

Guidelines for Patch Submission

+ +

+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. +

+ +

+ +Please +log in +to your tigris.org account before submitting any patch + +
+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. +
+
+If your patch is extensive, discuss it first on the +dev@scons.tigris.org +mailing list + +
+In fact, for extensive changes, it's a good idea to have this discusssion +before you invest too much time in coding. +It's possible that your idea would overlap 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 +only to have it rejected. +
+
+It's better to submit multiple patches with separate bits of functionality than a big patch containing lots of changes +
+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.
+
+Submit your patch in diff -u or diff -c format
-More information coming soon... +In particular, do not submit whole source files, +or diff output without any kind of context information. +It's much more difficult to integrate whole source files +or plain diff output with other changes to +the SCons code base.
+
+Your patch must include test caes before it can be integrated! +
+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: +
+
- +Include actual new or modified SCons test scripts in 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.) +
  +
- +Include a .tar.gz or .zip file containing test configurations +
  +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. +
  +
- +Describe how to go about testing the patch +
  +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 any 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 cse. +
+
+Your patch should not break any existing tests +
+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 +before 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 +dev@scons.tigris.org +mailing list. +
+
+Your patch should include documentation changes +
+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 intent +of your change to figure out how to describe. +
+

+ +

Steps for Submitting a Patch

+ +

+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. +

+ +

+Log in at tigris.org +
+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. +
+
+Go to the "Enter issue" page at +http://scons.tigris.org/issues/enter_bug.cgi?subcomponent=scons&issue_type=PATCH + +
+
+
+Specify the version of SCons that you used as a baseline +
+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. +
+
+Fill in a good Summary line describing the patch +
+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. +
+
+Fill in the Description field +
+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. +
+
+Press the "Submit issue" to submit your report +
+You will now receive a Posting issue page +that gives you the number of the issue you submitted. +
+
+Click the "Attach a file to this issue" link +
+
+
+Fill in the "File" field with the path to the file you want to upload +
+(You can also do this through the Browse... button.) +
+
+Fill in the Description field +
+
+
+Click the "Submit" button to attach your file +
+
+

scons
Bug Submission Guidelines

scons
Bug Submission

scons
Feature Request Guidelines

scons
Feature Requests

Steps for Submitting a Feature Request

scons
Patch Submission Guidelines

scons
Patch Submission

Guidelines for Patch Submission

Steps for Submitting a Patch

sconsBug Submission Guidelines

sconsBug Submission

sconsFeature Request Guidelines

sconsFeature Requests

Steps for Submitting a Feature Request

sconsPatch Submission Guidelines

sconsPatch Submission

Guidelines for Patch Submission

Steps for Submitting a Patch

scons
Bug Submission Guidelines

scons
Bug Submission

scons
Feature Request Guidelines

scons
Feature Requests

scons
Patch Submission Guidelines

scons
Patch Submission