1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
|
<html>
<head>
<title>Patch Submission</title>
</head>
<body>
<div id="apphead">
<h1><small>scons</small><br />Patch Submission</h1>
</div>
<p>
<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 the
<a href="http://scons.tigris.org/issues/enter_bug.cgi?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,
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 its integration,
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 patch 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
<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 caes 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 might still take someone else 15 or more minutes
of making sure they understand your 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 <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 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 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,
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 patch 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
<a href="http://scons.tigris.org/issues/enter_bug.cgi?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>
|
