3 The &SCons; project has paid particular attention from day one to the
4 development process. One of the first internal documents produced was
5 a set of Developer's Guidelines to provide a loose framework for what
6 we were trying to accomplish and how we would go about accomplishing
7 it. These Guidelines cover things like:
16 &SCons; will be written to Python version 1.5.2 (to ensure
17 usability by a wide install base).
25 How &SCons; is be tested: which infrastructure modules to use,
26 what platforms to test on, etc.
34 Expectations for developers (subscribe to the mailing list,
35 encouraged to register at SourceForge).
43 Brief outline of how to use the change management systems (Aegis and
44 CVS) for &SCons; development;.
53 Establishing these guidelines up front had two purposes: 1)
54 Demonstrate the seriousness of the project to anyone wondering about
55 joining the effort; 2) Give potential developers an idea up front as
56 to whether their development style would mesh with the rest of the
66 One of the most important aspects of the &SCons; development process
67 is the use of Peter Miller's Aegis change management system. I
68 had been using Aegis for personal projects for several years, and
69 found its development methodology vastly improved the quality of my
70 programming. I was consequently committed to using it for &SCons;
77 Aegis provides a number of things, including:
86 A flexible source code control and branching model.
94 A defined process with separate development, review and
103 A distributed development model based on distribution of atomic
113 The single most important reason for using Aegis, however, is its
114 management of automated tests as part of the development process.
121 <title>Testing, Testing, Testing</title>
125 The &SCons; project has made extensive use of automated tests from day
126 one, taking inspiration mostly from Aegis, partly from the eXtreme
127 Programming model, and with a little home-brew scripting for glue.
132 <title>Testing Criteria</title>
136 The underlying criteria for testing changes to the &SCons; code
137 are taken from Aegis:
146 Every change must have one or more new or modified tests
147 checked in along with the code.
155 The new code being checked in must pass all of the new and/or
164 The <emphasis>old</emphasis>, already checked-in code in must
165 <emphasis>fail</emphasis> all of the new and/or modified
174 The new code being checked in must pass all unmodified,
175 already checked-in tests.
184 In practice, these restrictions can be overridden as necessaryfor
185 example, when changing comments or documentation.
191 The criterion that surprises many people is having the old code
192 fail the tests in the change. This makes sure that the new tests
193 or modified tests really do exercise the bug fix or feature being
200 Together, these criteria ensure that every newly checked-in
201 version &SCons; conforms to defined behavior, as defined by
202 the tests. Whenever a bug is found, its fix is checked in with
203 a new or modified test that guarantees the bug will not recur
204 in the future. We have already built up a regression test base
205 of almost 90 tests that cover the vast majority of &SCons;'
213 <title>Testing Infrastructure</title>
217 Testing standards are no good if they're too much of a burden for
218 developers, who will at best work around or ignore the testing
219 requirements, or at worst stop contributing code and go join a
220 project that's more fun. To this end, good testing infrastructure
221 that makes it easy to write tests is crucial.
227 &SCons; development uses two development methodologies, one for
228 the individual modules in the build engine, and the other for
229 end-to-end tests of the &SCons; script.
235 For the build engine modules, we use PyUnit. Every change to a
236 build engine module must have a change to its corresponding unit
237 tests, which live side-by-side in a separate file that imports
238 module. As we build up a large body of unit tests, this ensures
239 that the build engine will perform correctly whenever someone uses
240 it in some application other than the &SCons; script itself.
246 For end-to-end script tests, we have developed two modules to make
247 writing tests easy. The first, <filename>TestCmd.py</filename>,
248 is a generic module for
249 testing commands or scripts (in any language, not just Python).
251 The second module, <filename>TestScons.py</filename>,
252 is a subclass of the generic
253 <filename>TestCmd.py</filename> module.
254 <filename>TestScons.py</filename>
255 takes care of initialization and
256 displaying error conditions
257 specific to testing &SCons;.
263 In practice, simple tests only
264 need to initialize a test object, use the object to write some
265 input files, run &SCons;, and then check whatever criteria
266 determine whether the test passed or failed. A complete test of
267 the &Program; method, for example, looks like this:
272 test = TestSCons.TestSCons()
274 test.write('SConstruct',
275 """env = Environment()
276 env.Program(target = 'foo', source = 'foo.c')
282 main(int argc, char *argv[])
284 argv[argc++] = "-"; /* dummy use of args */
285 printf("foo.c successfully compiled\\n");
290 test.run(arguments = 'foo') # runs SCons
292 test.run(program = test.workpath('foo'))
294 test.fail_test(test.stdout() != "foo.c successfully compiled\n")
304 <title>SourceForge</title>
308 Registration of the &SCons; project was approved at SourceForge on
309 29 June 2001. Within a week, the initial code base was checked in,
310 mailing lists were created, and the web site was set up. We started
311 making use of the task-list manager to track what we had to finish
318 The obvious complication was how to use
319 structured testing methodology of Aegis when SourceForge uses
320 CVS for source control. Not using the SourceForge CVS tree would
321 have had two significant disadvantages: one, missing out on the
322 archiving and central location in the event of disaster; two, people
323 coming to the SourceForge project page wouldn't be able to browse
324 the source. The latter was particularly important in
325 the early stages of development, in order to avoid any impression
326 that this was Yet Another Project that starts with a bang and then
327 dwindles as the initial enthusiasm starts to wear off.
333 The solution was to use the SourceForge CVS repository for read-only
334 access to the source. &SCons; developers are welcome to use CVS for
335 their development, but the changes are <emphasis>not</emphasis>
336 committed to the SourceForge repository. Instead, patches are sent
337 to the integrator for processing through Aegis. When the change
338 has been integrated into the Aegis repository, a home-brew
339 script translates the Aegis change into a virtual shell script
340 of commands that copy the necessary files from Aegis and check them
341 in to CVS at SourceForge.
347 (In practice, write access is not actually disabled for registered
348 developers, but if they do make any changes directly at SourceForge,
349 they can be overwritten at the next Aegis update.)