Initial text for patch and feature pages.

Title change and minor wording changes for bug page.
author: Steven Knight <knight@baldmt.com> 2006-05-21 21:48:11 (GMT)
committer: Steven Knight <knight@baldmt.com> 2006-05-21 21:48:11 (GMT)
commit: 57a1b02760ed0ce6837f43582cae1925e716fc48 (patch)
tree: 981344bbea1bd3f6c35af384b5da80908aa78a52
parent: c884a8b9b76a5cbffa347eb699d526d2a6d4f761 (diff)
download: SCons-57a1b02760ed0ce6837f43582cae1925e716fc48.zip
SCons-57a1b02760ed0ce6837f43582cae1925e716fc48.tar.gz
SCons-57a1b02760ed0ce6837f43582cae1925e716fc48.tar.bz2
3 files changed, 400 insertions, 15 deletions
diff --git a/www/bug-submission.html b/www/bug-submission.html
index 2fe3a9c..0774949 100644
--- a/www/bug-submission.html
+++ b/www/bug-submission.html
@@ -1,11 +1,11 @@
 <html>
 <head>
-<title>Bug Submission Guidelines</title>
+<title>Bug Submission</title>
 </head>
 <body>
 
 <div id="apphead">
-<h1><small>scons</small><br />Bug Submission Guidelines</h1>
+<h1><small>scons</small><br />Bug Submission</h1>
 
 <p>
 <strong>If you have not already done so, please
@@ -65,7 +65,6 @@ in the bug description.
 </li>
 <li>
 <strong>Specify the version of SCons in which you observed the problem</strong>
-</strong>
 <p>
 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.
 </p>
 <p>
-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.
 </p>
@@ -146,7 +144,7 @@ as described below.
 
 <ul>
 <li>
-<strong>Log in at tigris.org</strong>
+<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,
 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 <strong>Browse...</strong> button.)
 </li>
 <li>
-<strong>Fill in the Description fied</strong>
+<strong>Fill in the Description field</strong>
 </li>
 <li>
 <strong>Click the "Submit" button</strong>
diff --git a/www/feature-request.html b/www/feature-request.html
index 707379a..a912ab6 100644
--- a/www/feature-request.html
+++ b/www/feature-request.html
@@ -1,20 +1,87 @@
 <html>
 <head>
-<title>Feature Request Guidelines</title>
+<title>Feature Requests</title>
 </head>
 <body>
 
 <div id="apphead">
-<h1><small>scons</small><br />Feature Request Guidelines</h1>
+<h1><small>scons</small><br />Feature Requests</h1>
 </div>
 
 <p>
-<a href="http://scons.tigris.org/issues/enter_bug.cgi?issue_type=FEATURE?subcomponent=scons">http://scons.tigris.org/issues/enter_bug.cgi?issue_type=FEATURE?subcomponent=scons</a>
+<strong>If you have not already done so, please
+<a href="http://www.tigris.org/servlets/Login">log in</a>
+before submitting a feature request!</strong>
+<p>
+
+<p>
+Feature requests should be submitted to
+<a href="http://scons.tigris.org/issues/enter_bug.cgi?subcomponent=scons&issue_type=FEATURE">http://scons.tigris.org/issues/enter_bug.cgi?subcomponent=scons&issue_type=FEATURE</a>
+A more detailed set of <a href="feature-request.html#steps">submission steps</a>
+can be found below.
+</p>
+
+</div>
+
+<div class="h2 app" style="border-left: 0px" id="customcontent">
+
+<h2 id="steps">Steps for Submitting a Feature Request</h2>
+
+<p>
+The following guides you step-by-step through the
+process of submitting a feature request.
 </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,
+you can register for one at
+<a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>.
+</p>
+<p>
+You can still submit a feature request anonymously, without logging in.
+If you choose not to create a tigris.org account,
+putting some identifying contact information
+in the description will be helpful in case
+the feature request requires some clarification.
+</p>
+</li>
+<li>
+<strong>Go to the "Enter issue" page at
+<a href="http://scons.tigris.org/issues/enter_bug.cgi?subcomponent=scons&issue_type=FEATURE">http://scons.tigris.org/issues/enter_bug.cgi?subcomponent=scons&issue_type=FEATURE</a>
+</strong>
+<p>
+</p>
+</li>
+<li>
+<strong>Fill in a good Summary line describing the feature you're requesting</strong>
+<p>
+This line is what shows up in summary reports,
+so it should be descriptive but not too long.
+</p>
+</li>
+<li>
+<strong>Fill in the Description field</strong>
+<p>
+This is where you should go into detail
+about what you have in mind for SCons.
+When in doubt, include more information rather than less.
+</p>
+</li>
+<li>
+<strong>Press the "Submit issue" to submit your request</strong>
 <p>
-More information coming soon...
+You will now receive a <strong>Posting issue</strong> page
+that gives you the number of the issue you submitted.
+If you want to attach a file to your feature request,
+you can do so by clicking the
+<strong>Attach a file to this issue</strong>
+link and using that page to upload a file.
 </p>
+</li>
+</ul>
 
 </div>
 
diff --git a/www/patch-submission.html b/www/patch-submission.html
index a5ca9e4..6d0bfd6 100644
--- a/www/patch-submission.html
+++ b/www/patch-submission.html
@@ -1,20 +1,340 @@
 <html>
 <head>
-<title>Patch Submission Guidelines</title>
+<title>Patch Submission</title>
 </head>
 <body>
 
 <div id="apphead">
-<h1><small>scons</small><br />Patch Submission Guidelines</h1>
+<h1><small>scons</small><br />Patch Submission</h1>
 </div>
 
 <p>
-<a href="http://scons.tigris.org/issues/enter_bug.cgi?issue_type=PATCH?subcomponent=scons">http://scons.tigris.org/issues/enter_bug.cgi?issue_type=PATCH?subcomponent=scons</a>
+<strong>If you have not already done so, please
+<a href="http://www.tigris.org/servlets/Login">log in</a>
+before submitting a patch!</strong>
+<p>
+
+<p>
+Patches should be submitted to
+<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>
+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>
+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.
+</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,
+please register for one at
+<a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>.
+</p>
+<p>
+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.
+</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
+<emphasis>before</emphasis> 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.
+</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 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.
 </p>
+</li>
 
+<li>
+<strong>Submit your patch in <tt>diff -u</tt> or <tt>diff -c</tt> format</strong>
 <p>
-More information coming soon...
+In particular, do <emphasis>not</emphasis> 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.
 </p>
+</li>
+
+<li>
+<strong>Your patch must include test caes before it can be integrated!</strong>
+<p>
+THIS IS THE SINGLE MOST COMMON REASON FOR DELAYS IN INTEGRATING PATCHES.
+</p>
+<p>
+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.
+</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.
+(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'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.
+</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 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.
+</p>
+</li>
+</ul>
+<p>
+If you don't supply <emphasis>any</emphasis> 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.
+</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 
+You should, of course, avoid this by running your patch
+against the regression tests and fixing any problems
+<emphasis>before</emphasis> 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 <emphasis>intent</emphasis>
+of your change to figure out how to describe.
+</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,
+you can register for one at
+<a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>.
+</p>
+<p>
+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.
+</p>
+</li>
+
+<li>
+<strong>Go to the "Enter issue" page at
+<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>
+</strong>
+<p>
+</p>
+</li>
+
+<li>
+<strong>Specify the version of SCons that you used as a baseline</strong>
+<p>
+You can leave this <strong>-unspecified-</strong>,
+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 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.
+</p>
+</li>
+
+<li>
+<strong>Press the "Submit issue" to submit your report</strong>
+<p>
+You will now receive a <strong>Posting issue</strong> 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 file you want to upload</strong>
+<p>
+(You can also do this through the <strong>Browse...</strong> button.)
+</p>
+</li>
+
+<li>
+<strong>Fill in the Description field</strong>
+<p>
+</p>
+</li>
+
+<li>
+<strong>Click the "Submit" button to attach your file</strong>
+<p>
+</p>
+</li>
+
+</ul>
 
 </div>
author	Steven Knight <knight@baldmt.com>	2006-05-21 21:48:11 (GMT)
committer	Steven Knight <knight@baldmt.com>	2006-05-21 21:48:11 (GMT)
commit	57a1b02760ed0ce6837f43582cae1925e716fc48 (patch)
tree	981344bbea1bd3f6c35af384b5da80908aa78a52
parent	c884a8b9b76a5cbffa347eb699d526d2a6d4f761 (diff)
download	SCons-57a1b02760ed0ce6837f43582cae1925e716fc48.zip SCons-57a1b02760ed0ce6837f43582cae1925e716fc48.tar.gz SCons-57a1b02760ed0ce6837f43582cae1925e716fc48.tar.bz2