summaryrefslogtreecommitdiff
path: root/doc/python10/process.xml
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2010-01-02 20:56:27 +0100
committerLuca Falavigna <dktrkranz@debian.org>2010-01-02 20:56:27 +0100
commit72c578fd4b0b4a5a43e18594339ac4ff26c376dc (patch)
treecadaf3abe37a1066ceae933bc8fe7b75c85f56d2 /doc/python10/process.xml
parent548ed1064f327bccc6e538806740d41ea2d928a1 (diff)
Imported Upstream version 1.2.0.d20091224upstream/1.2.0.d20091224
Diffstat (limited to 'doc/python10/process.xml')
-rw-r--r--doc/python10/process.xml353
1 files changed, 353 insertions, 0 deletions
diff --git a/doc/python10/process.xml b/doc/python10/process.xml
new file mode 100644
index 0000000..f1b2479
--- /dev/null
+++ b/doc/python10/process.xml
@@ -0,0 +1,353 @@
+<para>
+
+ The &SCons; project has paid particular attention from day one to the
+ development process. One of the first internal documents produced was
+ a set of Developer's Guidelines to provide a loose framework for what
+ we were trying to accomplish and how we would go about accomplishing
+ it. These Guidelines cover things like:
+
+</para>
+
+<itemizedlist>
+
+ <listitem>
+ <para>
+
+ &SCons; will be written to Python version 1.5.2 (to ensure
+ usability by a wide install base).
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
+ How &SCons; is be tested: which infrastructure modules to use,
+ what platforms to test on, etc.
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
+ Expectations for developers (subscribe to the mailing list,
+ encouraged to register at SourceForge).
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
+ Brief outline of how to use the change management systems (Aegis and
+ CVS) for &SCons; development;.
+
+ </para>
+ </listitem>
+
+</itemizedlist>
+
+<para>
+
+ Establishing these guidelines up front had two purposes: 1)
+ Demonstrate the seriousness of the project to anyone wondering about
+ joining the effort; 2) Give potential developers an idea up front as
+ to whether their development style would mesh with the rest of the
+ project.
+
+</para>
+
+<section>
+ <title>Aegis</title>
+
+ <para>
+
+ One of the most important aspects of the &SCons; development process
+ is the use of Peter Miller's Aegis change management system. I
+ had been using Aegis for personal projects for several years, and
+ found its development methodology vastly improved the quality of my
+ programming. I was consequently committed to using it for &SCons;
+ development.
+
+ </para>
+
+ <para>
+
+ Aegis provides a number of things, including:
+
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+
+ A flexible source code control and branching model.
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
+ A defined process with separate development, review and
+ integration steps.
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
+ A distributed development model based on distribution of atomic
+ change sets.
+
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+
+ The single most important reason for using Aegis, however, is its
+ management of automated tests as part of the development process.
+
+ </para>
+
+</section>
+
+<section>
+ <title>Testing, Testing, Testing</title>
+
+ <para>
+
+ The &SCons; project has made extensive use of automated tests from day
+ one, taking inspiration mostly from Aegis, partly from the eXtreme
+ Programming model, and with a little home-brew scripting for glue.
+
+ </para>
+
+ <section>
+ <title>Testing Criteria</title>
+
+ <para>
+
+ The underlying criteria for testing changes to the &SCons; code
+ are taken from Aegis:
+
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+
+ Every change must have one or more new or modified tests
+ checked in along with the code.
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
+ The new code being checked in must pass all of the new and/or
+ modified tests.
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
+ The <emphasis>old</emphasis>, already checked-in code in must
+ <emphasis>fail</emphasis> all of the new and/or modified
+ tests.
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+
+ The new code being checked in must pass all unmodified,
+ already checked-in tests.
+
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+
+ In practice, these restrictions can be overridden as necessary­for
+ example, when changing comments or documentation.
+
+ </para>
+
+ <para>
+
+ The criterion that surprises many people is having the old code
+ fail the tests in the change. This makes sure that the new tests
+ or modified tests really do exercise the bug fix or feature being
+ added by the change.
+
+ </para>
+
+ <para>
+
+ Together, these criteria ensure that every newly checked-in
+ version &SCons; conforms to defined behavior, as defined by
+ the tests. Whenever a bug is found, its fix is checked in with
+ a new or modified test that guarantees the bug will not recur
+ in the future. We have already built up a regression test base
+ of almost 90 tests that cover the vast majority of &SCons;'
+ functionality.
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>Testing Infrastructure</title>
+
+ <para>
+
+ Testing standards are no good if they're too much of a burden for
+ developers, who will at best work around or ignore the testing
+ requirements, or at worst stop contributing code and go join a
+ project that's more fun. To this end, good testing infrastructure
+ that makes it easy to write tests is crucial.
+
+ </para>
+
+ <para>
+
+ &SCons; development uses two development methodologies, one for
+ the individual modules in the build engine, and the other for
+ end-to-end tests of the &SCons; script.
+
+ </para>
+
+ <para>
+
+ For the build engine modules, we use PyUnit. Every change to a
+ build engine module must have a change to its corresponding unit
+ tests, which live side-by-side in a separate file that imports
+ module. As we build up a large body of unit tests, this ensures
+ that the build engine will perform correctly whenever someone uses
+ it in some application other than the &SCons; script itself.
+
+ </para>
+
+ <para>
+
+ For end-to-end script tests, we have developed two modules to make
+ writing tests easy. The first, <filename>TestCmd.py</filename>,
+ is a generic module for
+ testing commands or scripts (in any language, not just Python).
+
+ The second module, <filename>TestScons.py</filename>,
+ is a subclass of the generic
+ <filename>TestCmd.py</filename> module.
+ <filename>TestScons.py</filename>
+ takes care of initialization and
+ displaying error conditions
+ specific to testing &SCons;.
+
+ </para>
+
+ <para>
+
+ In practice, simple tests only
+ need to initialize a test object, use the object to write some
+ input files, run &SCons;, and then check whatever criteria
+ determine whether the test passed or failed. A complete test of
+ the &Program; method, for example, looks like this:
+
+ </para>
+
+ <programlisting>
+ test = TestSCons.TestSCons()
+
+ test.write('SConstruct',
+ """env = Environment()
+ env.Program(target = 'foo', source = 'foo.c')
+ """)
+
+ test.write('foo.c',
+ """
+ int
+ main(int argc, char *argv[])
+ {
+ argv[argc++] = "-"; /* dummy use of args */
+ printf("foo.c successfully compiled\\n");
+ exit (0);
+ }
+ """)
+
+ test.run(arguments = 'foo') # runs SCons
+
+ test.run(program = test.workpath('foo'))
+
+ test.fail_test(test.stdout() != "foo.c successfully compiled\n")
+
+ test.pass_test()
+ </programlisting>
+
+ </section>
+
+</section>
+
+<section>
+ <title>SourceForge</title>
+
+ <para>
+
+ Registration of the &SCons; project was approved at SourceForge on
+ 29 June 2001. Within a week, the initial code base was checked in,
+ mailing lists were created, and the web site was set up. We started
+ making use of the task-list manager to track what we had to finish
+ for initial release.
+
+ </para>
+
+ <para>
+
+ The obvious complication was how to use
+ structured testing methodology of Aegis when SourceForge uses
+ CVS for source control. Not using the SourceForge CVS tree would
+ have had two significant disadvantages: one, missing out on the
+ archiving and central location in the event of disaster; two, people
+ coming to the SourceForge project page wouldn't be able to browse
+ the source. The latter was particularly important in
+ the early stages of development, in order to avoid any impression
+ that this was Yet Another Project that starts with a bang and then
+ dwindles as the initial enthusiasm starts to wear off.
+
+ </para>
+
+ <para>
+
+ The solution was to use the SourceForge CVS repository for read-only
+ access to the source. &SCons; developers are welcome to use CVS for
+ their development, but the changes are <emphasis>not</emphasis>
+ committed to the SourceForge repository. Instead, patches are sent
+ to the integrator for processing through Aegis. When the change
+ has been integrated into the Aegis repository, a home-brew
+ script translates the Aegis change into a virtual shell script
+ of commands that copy the necessary files from Aegis and check them
+ in to CVS at SourceForge.
+
+ </para>
+
+ <para>
+
+ (In practice, write access is not actually disabled for registered
+ developers, but if they do make any changes directly at SourceForge,
+ they can be overwritten at the next Aegis update.)
+
+ </para>
+
+</section>