<html>
<head>
-<title>scons: Patch Submission Guidelines</title>
+<title>Patch Submission</title>
</head>
<body>
<div id="apphead">
-<h1><small>Patch Submission Guidelines</small></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>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>
-More information coming soon...
+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>
projects / scons.git / blobdiff