SCons Developer's Guidelines

6 February 2007
  1. General

    1. All SCons software (SCons itself, tests, supporting utilities) will be written to work with Python version 1.5.2.
    2. SCons will be tested against Python versions 1.5.2 and some version of 2.x.
    3. The SCons distribution will be generated by the distutils package.
    4. SCons will not require installation of any additional Python modules or packages. All modules or packages used by SCons must either be part of the standard Python 1.5.2 release or be part of the SCons distribution.
    5. SCons installation will be atomic, and will install all necessary non-standard modules and/or packages.
    6. At a minimum, SCons will be tested on Linux and Windows XP. We will add other platforms as they become available. All tests must be written portably.
    7. SCons software will be written to a separately-defined set of conventions (variable naming, class naming, etc.). We won't be dogmatic about these, and will use discretion when deciding whether a naming violation is significant enough to require a fix.
    8. SCons is being developed using the following source code control system(s):
      1. The main source tree is kept in Subversion at tigris.org.
      2. A public CVS copy of the source tree is maintained at SourceForge for archival purposes, for public availability, and to support read-only CVS development.
      3. SK is still using the Aegis change management system for his back-end development process, primarily for its management of tests. The SCons packaging is still written assuming an Aegis infrastructure, but will change to Subversion-based packaging at some point.
    9. QMTest is the default driver for all tests. Individual tests are written using the following infrastructure pieces:
      1. SCons infrastructure module tests are written using PyUnit.
      2. Tests of SCons packaging are written using subclasses of the TestCmd.py module.
      3. Tests of full SCons script functionality are written using subclasses of the TestCmd.py module.

  2. Development philosophy

    In a word (x3): Testing, testing, testing.

    We're growing a rich set of regression tests incrementally, while SCons is being developed. The goal is to produce an exceptionally stable, reliable tool of known, verifiable quality right from the start.

    A strong set of tests allows us to guarantee that everything works properly even when we have to refactor internal subsystems, which we expect to have to do fairly often as SCons grows and develops. It's also great positive feedback in the development cycle to make a change, see the test(s) work, make another change, see the test(s) work...

  3. Testing methodology

    The specific testing rules we're using for SCons are as follows:

    1. Every functional change must have one or more new tests, or modify one or more existing tests.
    2. The new or modified test(s) must pass when run against your new code (of course).
    3. The new code must also pass all unmodified, checked-in tests (regression tests).
    4. The new or modified test(s) must fail when run against the currently checked-in code. This verifies that your new or modified test does, in fact, test what you intend it to. If it doesn't, then either there's a bug in your test, or you're writing code that duplicates functionality that already exists.
    5. Changes that don't affect functionality (documentation changes, code cleanup, adding a new test for existing functionality, etc.) can relax these restrictions as appropriate.

    These rules are taken from the Aegis change management system, which SK uses behind the scenes to manage SCons integrations (and his personal development process).

    The SCons testing infrastructure is largely in place, and is intended to make writing tests as easy and painless as possible. We will change the infrastructure as needed to continue to make testing even easier, so long as it still does the job.

    SCons development uses three (!) testing harnesses, one for unit tests, one for end-to-end functional tests, and one for test execution:

    • The infrastructure modules (under the src/scons subdirectory) all have individual unit tests that use PyUnit. The naming convention is to append "Tests" to the module name. For example, the unit tests for the src/scons/Foo.py module can be found in the src/scons/FooTests.py file.
    • The packaging is tested by test scripts that live in the src/ subdirectory and use a prefix of "test_".
    • The scons utility itself is tested by end-to-end tests that live in the test/ subdirectory and which use the TestCmd.py infrastructure.
    • Execution of these tests will be handled by the QMTest infrastructure, as wrapped by an execution script. Note: The transition to using QMTest is still in progress. The wrapper execution script currently executes the test scripts directly.

    The end-to-end tests in the test/ subdirectory are not substitutes for module unit tests. If you modify a module under the src/scons/ subdirectory, you generally mustmodify its *Tests.py script to validate your change. This can be (and probably should be) in addition to a test/* test of how the modification affects the end-to-end workings of SCons.

  4. General developer requirements

    1. All project developers must subscribe to the dev@scons.tigris.org mailing list.
    2. All project developers must register at Tigris.org and be added to the SCons developer list, so that the number of active developers can be accurately represented on the SCons project page.
    3. We will accept patches from developers not actually registered on the project, so long as the patches conform to our normal requirements.

  5. Using Subversion for SCons development

    1. Developers using Subversion may, but need not, be registered as Tigris.org or SourceForge developers.
    2. Developers using Subversion should submit patches following the normal patch submission guidelines.

  6. Integration

    1. The main line of SCons integration is still under the control of the Aegis change management system, as administered by SK on his system. We want move to Subversion-based integration and packaging.
    2. Changes to SK's main Aegis repository get propagated automatically to the Tigris.org and SourceForge CVS repositories.