[Zope3-checkins] SVN: Zope3/trunk/ - documentation updates

Christian Theune ct at gocept.com
Mon Apr 16 03:35:34 EDT 2007


Log message for revision 74165:
   - documentation updates
   - restification
  

Changed:
  U   Zope3/trunk/README.txt
  U   Zope3/trunk/doc/DEBUG.txt
  U   Zope3/trunk/doc/ENVIRONMENT.txt
  U   Zope3/trunk/doc/FAQ.txt
  U   Zope3/trunk/doc/FTEST.txt
  U   Zope3/trunk/doc/INSTALL.txt
  U   Zope3/trunk/doc/LOGGING.txt
  U   Zope3/trunk/doc/ROADMAP.txt
  U   Zope3/trunk/doc/UNITTEST.txt

-=-
Modified: Zope3/trunk/README.txt
===================================================================
--- Zope3/trunk/README.txt	2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/README.txt	2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,47 +1,49 @@
-===========================
-Welcome to the Zope3 source
-===========================
+============================
+Welcome to the Zope 3 source
+============================
 
-This file provides some basic hints for people developing Zope3 software.
-There is more developer info in the Zope 3 Wiki:
+This file provides some basic hints for people developing Zope 3 software.
+There is more developer info in the Zope 3 Wiki::
 
-  http://dev.zope.org/Zope3/Zope3DeveloperInfo
+  http://wiki.zope.org/Zope3/Zope3DeveloperInfo
 
 For information about the current release, see ``doc/CHANGES.txt``.
 
-Zope 3 is now a stable platform on which production systems can and are built.
+Zope 3 is a stable platform on which production systems can and are built.
 
 
 Building and running tests
---------------------------
+==========================
 
 See ``INSTALL.txt`` which Python version is required for Zope 3.
 
 In the top-level ``Zope3`` directory, you should find a script called
-setup.py.  Run it to build the extension modules needed by Zope.  Example::
+``setup.py``.  Run it to build the extension modules needed by Zope.  Example::
 
-  # cd Zope3
-  # python setup.py -q build_ext -i install_data --install-dir .
+    $ cd Zope3
+    $ python setup.py -q build_ext -i install_data --install-dir .
 
-On a unix variant, you can just type: ``make``
+On a Unix variant, you can just type::
 
+    $ make
+
 On Windows, if you downloaded the binary distribution, this has already been
 done for you (since the compiler we use on Windows isn't free).
 
-Zope 3 includes unit tests based on the Python unittest module.  If you check
-in changes, you should verify that all the tests succeed before you commit
-changes.
+Zope 3 includes unit tests based on the Python ``unittest`` module.  If you
+check in changes, you *must* verify that all the tests succeed before you
+commit changes.
 
 To run all the tests, use the script test.py::
 
-  # python test.py -v
+    $ python test.py -v
 
 Use ``test.py -h`` for usage.  The test script can run selected tests, stop
 after the first error, run the tests in a loop, etc.
 
 
 Starting Zope 3
----------------
+===============
 
 Before running Zope, you need to create one or more bootstrap users.  Copy the
 file ``sample_principals.zcml`` to ``principals.zcml``, and edit the result to
@@ -49,58 +51,58 @@
 
 To run Zope just run the ``z3.py`` script::
 
-  # python z3.py
+    $ python z3.py
 
 Or, if you use make on Unix, you can run::
 
-  # bin/runzope
+    $ bin/zopectl fg
 
 This will run Zope on port 8080.  Visit the url::
 
-  http://localhost:8080/manage
+    http://localhost:8080/manage
 
-This goes to the Zope 3 default management interface.  Note that
-this release of Zope 3 requires recent versions of Mozilla or IE.  Note that
-other modern browsers, such as Konqueror and Safari, also mostly work well.
+This goes to the Zope 3 default management interface.  Note that this release
+of Zope 3 requires recent versions of Mozilla or IE.  Note that other modern
+browsers, such as Konqueror and Safari, also mostly work well.
 
-If you insist on using an older browser (or a text-based browser)
-you can use the basic Zope 3 skin by putting ``++skin++Basic`` after
-the server part of the URL::
+If you insist on using an older browser (or a text-based browser) you can use
+the basic Zope 3 skin by putting ``++skin++Basic`` after the server part of
+the URL::
 
-  http://localhost:8080/++skin++Basic/manage
+    http://localhost:8080/++skin++Basic/manage
 
 See ``doc/INSTALL.txt`` for more information.
 
 
-Finding out how to develop new content types
---------------------------------------------
+Finding out how to develop applications
+=======================================
 
 There are several documentation sources out there. As of this writing two
 books have been published and much online documentation is available:
 
-  - Zope 3 comes with an extensive API documentation tool, which also compiles
-    many of the package-specific README files. Once you start up Zope, simply
-    go to:
+- Zope 3 comes with an extensive API documentation tool, which also compiles
+  many of the package-specific README files. Once you start up Zope, simply go
+  to::
 
-      http://localhost:8080/++apidoc++
+    http://localhost:8080/++apidoc++
 
-  - `Zope 3 Developer's Handbook`:
+- `Zope 3 Developer's Handbook`:
 
     * On Paper: http://www.samspublishing.com/title/0672326175
 
     * Online: http://dev.zope.org/Zope3/Zope3Book
 
-  - `Web Component Development with Zope 3`:
+- `Web Component Development with Zope 3`:
 
     * On Paper: http://www.springeronline.com/sgw/cda/frontpage/0,11855,1-102-22-35029949-0,00.html
 
     * Online: http://www.worldcookery.com
 
-  - The developers tutorial at:
+- The developers tutorial at:
 
     http://dev.zope.org/Zope3/ProgrammerTutorial
 
-  - Ask questions on the mailing lists and chat channels:
+- Ask questions on the mailing lists and chat channels:
 
     * Zope 3 Development: ``http://lists.zope.org/mailman/listinfo/zope3-dev``
 
@@ -108,12 +110,12 @@
 
     * IRC channel `#zope3-dev` on irc.freenode.net
 
-  - To keep up with the latest changes, the commits mailing list
-    ``http://lists.zope.org/mailman/listinfo/zope3-checkins``
+- To keep up with the latest changes, the commits mailing list
+  ``http://lists.zope.org/mailman/listinfo/zope3-checkins``
 
 
 Acknowledgements
-----------------
+================
 
 Zope 3 is a Zope Community effort.  There are many Zope 3 contributors without
 whom there wouldn't be a Zope 3.

Modified: Zope3/trunk/doc/DEBUG.txt
===================================================================
--- Zope3/trunk/doc/DEBUG.txt	2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/DEBUG.txt	2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,3 +1,4 @@
+=======================
 Using the Zope Debugger
 =======================
 
@@ -2,53 +3,53 @@
 Introduction
-------------
-  
-Zope3 includes a mechanism to debug an object publishing request,
-similar to the `Zope 2 debug mechanism`_
+============
 
+Zope 3 includes a mechanism to debug an object publishing request, similar to
+the `Zope 2 debug mechanism`_
+
 .. _Zope 2 debug mechanism: http://www.zope.org/Members/mcdonc/HowTos/UsingTheZopeDebugger
 
 
 Setting up the environment
---------------------------
+==========================
 
-Setup your PYTHONPATH environment variable to include src. ie (unix
-bash syntax):
+Setup your PYTHONPATH environment variable to include ``src/``. ie (unix
+bash syntax)::
 
-  cd Zope3
-  export PYTHONPATH=$PWD/src:$PYTHONPATH
-    
+    $ cd Zope3
+    $ export PYTHONPATH=$PWD/src:$PYTHONPATH
+
 To start interacting with the debugger you need to initialize the zope
-application:
+application::
 
-  $ python2.4
-  >>> from zope.app.debug import Debugger
-  >>> debugger = Debugger()
+    $ python2.4
+    >>> from zope.app.debug import Debugger
+    >>> debugger = Debugger()
 
-Note that you can pass a database file name and a site ZCML file to
-the debugger:
+Note that you can pass a database file name and a site ZCML file to the
+debugger::
 
-  >>> Debugger('path/to/zodb/', 'path/to/site.zcml')
-          
+    >>> Debugger('path/to/zodb/', 'path/to/site.zcml')
+
 But you can generally let the debugger figure out where they are.
-XXX In the future, the debugger should have it's own ZConfig file.
 
+(XXX In the future, the debugger should have it's own ZConfig file.)
 
 Alternatively, you can also use the ``zopectl`` script to initiate the
-debugger.  It will start up the Zope 3 instance without the servers
-and drop into a regular Python prompt, with the Debugger instance
-bound to the ``debugger`` variable:
+debugger.  It will start up the Zope 3 instance without the servers and drop
+into a regular Python prompt, with the Debugger instance bound to the
+``debugger`` variable::
 
-  $ bin/zopectl debug
-  >>> debugger
-  <zope.app.debug.debug.Debugger object at 0x660350>
+    $ bin/zopectl debug
+    >>> debugger
+    <zope.app.debug.debug.Debugger object at 0x660350>
 
-For people with Zope 2 experience, the debugger is also available
-under the name ``app``:
+For people with Zope 2 experience, the debugger is also available under the
+name ``app``::
 
-  >>> app
-  <zope.app.debug.debug.Debugger object at 0x660350>
+    >>> app
+    <zope.app.debug.debug.Debugger object at 0x660350>
 
 
 Using the Debugger
-------------------
+==================
 
@@ -58,35 +59,34 @@
 testing purposes.
 
 Publish
-~~~~~~~
+-------
 
 The ``publish`` method executes a request as the publisher would and
-prints the response headers and body:
+prints the response headers and body::
 
-  >>> debugger.publish(path='/folder/content_object')
+    >>> debugger.publish(path='/folder/content_object')
 
 Run
-~~~
+---
 
 The ``run`` method executes a request with the publisher's normal
 error handling disabled and without outputting anything.  This is
-useful for use with Python's post-mortem.
+useful for use with Python's post-mortem::
 
-  >>> debugger.run(path='/folder/content_object')
-  # an exception is raised
-  >>> import pdb; pdb.pm()
-  # enters the python post-mortem debugger
+    >>> debugger.run(path='/folder/content_object')
+    # an exception is raised
+    >>> import pdb; pdb.pm()
+    # enters the python post-mortem debugger
 
 Debug
-~~~~~      
+-----
 
-The 'debug' method starts up the publisher in the python debugger,
-with an extra convenience break point, setup just before the published
-object call:
+The ``debug`` method starts up the publisher in the python debugger, with an
+extra convenience break point, setup just before the published object call::
 
-  >>> debugger.debug(path='/folder/content_object')
-  * Type c<cr> to jump to published object call.
-  pdb> 
+    >>> debugger.debug(path='/folder/content_object')
+    * Type c<cr> to jump to published object call.
+    pdb> 
 
 Arguments: All of the debugger object's debug methods take optional
 arguments, the more common/useful ones...
@@ -98,18 +98,17 @@
 
 
 Accessing objects (without the debugger)
-----------------------------------------
+========================================
 
-You can use the application object to open a database connection to
-access your objects.  If the application object is called, it opens a
-database connection and fetches the root object:
+You can use the application object to open a database connection to access
+your objects.  If the application object is called, it opens a database
+connection and fetches the root object::
 
-  root = debugger.root()
+    >>> root = debugger.root()
 
-For example, to list the objects in the root folder:
+For example, to list the objects in the root folder::
 
-  print list(root)
+    >>> print list(root)
 
-Also note that, after initializing the application, by creating the
-root object, you can access any global services setup during
-initialization.
+Also note that, after initializing the application, by creating the root
+object, you can access any global services setup during initialization.

Modified: Zope3/trunk/doc/ENVIRONMENT.txt
===================================================================
--- Zope3/trunk/doc/ENVIRONMENT.txt	2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/ENVIRONMENT.txt	2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,21 +1,20 @@
-Usage of environment variables:
+==============================
+Usage of environment variables
+==============================
 
-  - The test suite uses the LOGGING variable to determine the PEP 282
-    logging level.  This should be a decimal number with the following
-    meaning: 10 DEBUG, 20 INFO, 30 WARN, 40 ERROR, 50 CRITICAL
-    (default).
+- The test suite uses the LOGGING variable to determine the PEP 282 logging
+  level.  This should be a decimal number with the following meaning: 10
+  DEBUG, 20 INFO, 30 WARN, 40 ERROR, 50 CRITICAL (default).
 
-  - Some ZEO code still uses environment variables, in particular
-    ZEO_CACHE_TRACE, ZEO_CLIENT, INSTANCE_HOME, ZEO_SERVER_PID.
+- Some ZEO code still uses environment variables, in particular
+  ZEO_CACHE_TRACE, ZEO_CLIENT, INSTANCE_HOME, ZEO_SERVER_PID.
 
-  - ZOPE_WATCH_CHECKERS used by src/zope/security/checker.py.
+- ZOPE_WATCH_CHECKERS used by src/zope/security/checker.py.
 
-  - ZOPE_SERVER_SIMULT_MODE used by src/zope/server/serverchannelbase.py.
+- ZOPE_SERVER_SIMULT_MODE used by src/zope/server/serverchannelbase.py.
 
-  - ZOPE_SERVER_DEBUG used by
-    src/zope/server/linereceiver/lineserverchannel.py.
+- ZOPE_SERVER_DEBUG used by src/zope/server/linereceiver/lineserverchannel.py.
 
-  - NEW_ZOPE_EXCEPTION_FORMATTER used by src/zope/testing/.
+- NEW_ZOPE_EXCEPTION_FORMATTER used by src/zope/testing/.
 
-  - PYUNIT_EDITOR, EDITOR, EDITOR_REMOTE used by
-    utilities/unittestgui.py.
+- PYUNIT_EDITOR, EDITOR, EDITOR_REMOTE used by utilities/unittestgui.py.

Modified: Zope3/trunk/doc/FAQ.txt
===================================================================
--- Zope3/trunk/doc/FAQ.txt	2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/FAQ.txt	2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,4 +1,5 @@
+============================================
 Zope Installation Frequently Asked Questions
---------------------------------------------
+============================================
 
-  See http://dev.zope.org/Zope3/FAQ
\ No newline at end of file
+See http://dev.zope.org/Zope3/FAQ

Modified: Zope3/trunk/doc/FTEST.txt
===================================================================
--- Zope3/trunk/doc/FTEST.txt	2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/FTEST.txt	2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,81 +1,72 @@
+=========================
 Zope 3 Functional Testing
+=========================
 
- How to run Zope 3 functional tests
+How to run Zope 3 functional tests
 
-  In the top-level directory, run "python test.py -f".  If you've read
-  UNITTEST.txt you'll notice that the same script is used, but with an
-  additional argument '-f'.  That's because in Zope 3 functional tests are
-  just a special case of unit tests.  The rest of test.py options work as
-  well, for example you can use "python test.py -fpv" to get a nice progress
-  indicator.  For information about all options run "python test.py -h".
+In the top-level directory, run "python test.py -f".  If you've read
+UNITTEST.txt you'll notice that the same script is used, but with an
+additional argument '-f'.  That's because in Zope 3 functional tests are just
+a special case of unit tests.  The rest of test.py options work as well, for
+example you can use "python test.py -fpv" to get a nice progress indicator.
+For information about all options run "python test.py -h".
 
-  If your Zope 3 doesn't yet have a products.zcml, create one by
-  copying products.zcml.in to products.zcml.
+Zope Functional Testing
+=======================
 
- Zope Functional Testing
+Functional tests use special ``test layers`` that set up more environment than
+normal unit tests do. E.g. the parse nearly all ZCML configuration files and
+create a virtual in-memory storage before running the tests.  Any changes made
+to the storage will be discarded at the end of the test.
 
-  Functional tests live in directories called "ftests" all over the source
-  tree.  They use the same PyUnit framework as unit tests, and I recommend
-  reading UNITTEST.txt and familiarizing with unit tests before moving on to
-  functional tests.
+Note: We recommend reading UNITTEST.txt and familiarize yourself with unit tests
+before moving on to functional tests.
 
-  Functional tests differ from unit tests in that nearly all ZCML configuration
-  files are parsed and a virtual in-memory storage is created before running
-  them.  Any changes made to the storage will be discarded at the end of the
-  test.
 
- What Functional Tests Are
+What Functional Tests Are
+=========================
 
-  Functional tests are meant to test more than just a single unit of code.
-  While unit tests make sure that all components work as designed, functional
-  tests ensure that those components are connected correctly, and that the
-  system works as a whole.
+Functional tests are meant to test more than just a single unit of code.
+While unit tests make sure that all components work as designed, functional
+tests ensure that those components are connected correctly, and that the
+system works as a whole.
 
- Writing Functional Tests
+Writing Functional Tests
+========================
 
-  Functional tests in Zope 3 use the same conventions as unit tests, but with
-  the following differences:
+Functional tests in Zope 3 use the same conventions as unit tests, but with
+the following differences:
 
-   - Functional test modules live in directories called 'ftests'.
+- Functional test suites live in a special ``functional test layer``.
 
-   - Functional test cases inherit from
-     zope.testing.functional.FunctionalTestCase or
-     zope.testing.functional.BrowserTestCase instead of unittest.TestCase.
+- All global services, components etc. defined in assorted configure.zcml are
+  available during test run time.
 
-   - All global services, components etc. defined in assorted configure.zcml
-     are available during test run time.
+- A volatile in-memory storage with an empty root folder and all essential
+  services is available and is automatically cleaned after every test.  The
+  test code can access and modify the root folder by calling
+  self.getRootFolder().
 
-   - A volatile in-memory storage with an empty root folder and all essential
-     services is available and is automatically cleaned after every test.
-     The test code can access and modify the root folder by calling
-     self.getRootFolder().
+- Browser requests can be emulated by leveraging the test browser.  See the
+  documentation in ``src/zope/testbrowser/`` for detailed information.  Here
+  are a couple of simple examples::
 
-   - Browser requests can be emulated by inheriting from BrowserTestCase and
-     calling self.publish().  See the docstring in
-     src/zope/app/tests/functional.py for detailed information.  Here are a
-     couple of simple examples::
+    >>> from zope.testbrowser.testing import Browser
+    >>> browser = Browser()
+    >>> browser.open("http://localhost/")
+    >>> print browser.contents
+    <html>
+    ...
+    >>> browser.getLink('[contents]').click()
 
-        response = self.publish('/folder/object')
-        self.assertEquals(response.getStatus(), 200)
-        self.assert_(response.getBody().find("some text") != -1)
+- If you want to make changes made directly through access to
+  self.getRootFolder() available to a test browser request, make sure to
+  commit the transaction.  Here's how you do it::
 
-        response = self.publish(
-            '/something/action.html',
-            basic='username:password',
-            form={'id': u'foo', 'UPDATE_SUBMIT': u'Submit'})
-        self.assertEquals(response.getStatus(), 302)
-        self.assertEquals(response.getHeader('Location'),
-                          'http://localhost/something.html')
+    >>> import transaction
+    >>> transaction.commit()
 
-   - If you want to make changes made directly through access to
-     self.getRootFolder() available to an emulated request, make sure to commit
-     the transaction.  Here's how you do it::
-
-       import transaction
-       transaction.commit()
-
-   - Functional tests should not change any global registries.  In particular,
-     functional unit test cases should not inherit from
-     zope.testing.cleanup.CleanUp or any of the PlacelessSetup classes that
-     inherit from CleanUp.
-
+- Functional tests should not change any global registries.  In particular,
+  functional unit test cases should not inherit from
+  zope.testing.cleanup.CleanUp or any of the PlacelessSetup classes that
+  inherit from CleanUp.

Modified: Zope3/trunk/doc/INSTALL.txt
===================================================================
--- Zope3/trunk/doc/INSTALL.txt	2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/INSTALL.txt	2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,114 +1,106 @@
+========================================
 Building and installing Zope from source
-----------------------------------------
+========================================
 
-  This document describes building and installing Zope3 on Unix.
-  We will provide Windows instructions in later releases. We
-  will also provide binary releases for some platforms.
+This document describes building and installing Zope 3 on Unix.  We will
+provide Windows instructions in later releases. We will also provide binary
+releases for some platforms.
 
 Important notes
+===============
 
-   ZOPE 3 REQUIRES PYTHON 2.4.1!
+ZOPE 3 REQUIRES PYTHON 2.4.4!
 
 Quick Start
+===========
 
-  The following commands should get you up and running with the
-  development version of Zope3 on Unix:
+The following commands should get you up and running with the development
+version of Zope 3 on Unix:
 
-    * If you have not yet checked out the Subversion tree, do so::
+* If you have not yet checked out the Subversion tree, do so::
 
-         svn co svn://svn.zope.org/repos/main/Zope3/trunk/ Zope3
+    $ svn co svn://svn.zope.org/repos/main/Zope3/trunk/ Zope3
+    $ cd Zope3
+    $ make
 
-    * cd Zope3
+* Copy sample_principals.zcml to principals.zcml, and edit the entries in your
+  new principals.zcml.  At the very least, change the passwords!
 
-    * python setup.py build_ext -i
+* Run the server::
+  
+    $ bin/zopectl fg
 
-      (On Unix, typing "make" will do the same thing.)
+You should shortly see logging messages indicating Zope 3 is listening on port
+8080.  At that point you can connect to Zope 3 by directing your browser to::
 
-    * Copy sample_principals.zcml to principals.zcml, and edit the
-      entries in your new principals.zcml.  At the very least, change
-      the passwords!
+    http://localhost:8080/manage
 
-    * python z3.py
+This will access the Zope 3 default management interface.  Note that this
+release of Zope 3 requires recent versions of Mozilla or IE.
 
-      (On Unix, typing "make run" will do the same thing.)
+If you insist on using an older browser (or a text-based browser) you can use
+the basic Zope 3 skin by putting '++skin++Basic' after the server part of the
+URL::
 
-  You should shortly see logging messages indicating Zope3 is listening on
-  port 8080.  At that point you can connect to Zope3 by directing
-  your browser to::
-
-     http://yourhost:8080/manage
-
-  where yourhost is the name or address of the machine running Zope 3.
-
-  This will access the Zope 3 default management interface.  Note that
-  this release of Zope 3 requires recent versions of Mozilla or IE.
-
-  If you insist on using an older browser (or a text-based browser)
-  you can use the basic Zope 3 skin by putting '++skin++Basic' after
-  the server part of the URL::
-
     http://localhost:8080/++skin++Basic/manage
 
-  You will be prompted for a user name and password. Use the user name
-  and password you entered into your principals.zcml file.
+You will be prompted for a user name and password. Use the user name and
+password you entered into your ``principals.zcml`` file.
 
-  Now you're off and running!
+Now you're off and running!
 
 Resources
+=========
 
-  If you haven't used Zope3 before, you should head to the Zope web
-  site and read some documentation. The Zope 3 Python Programmers
-  Tutorial is a good place to start.  You can access it on the Zope
-  site at::
+If you haven't used Zope 3 before, you should head to the Zope web site and
+read some documentation. The Zope 3 Python Programmers Tutorial is a good
+place to start.  You can access it on the Zope site at::
 
     http://dev.zope.org/Zope3/ProgrammerTutorial
 
-  You will also find some additional documentation in the 'doc'
-  directory of the Zope3 tree, where this file lives.  All other
-  existing Zope3 documentation is linked from somewhere in the Zope
-  project Wiki::
+You will also find some additional documentation in the 'doc' directory of the
+Zope 3 tree, where this file lives.  All other existing Zope 3 documentation
+is linked from somewhere in the Zope project Wiki::
 
-    http://dev.zope.org/Zope3/ComponentArchitecture
+    http://wiki.zope.org/Zope3
 
-  You may also want to subscribe to the Zope3-dev mailing list::
+You may also want to subscribe to the Zope3-dev mailing list::
 
     http://lists.zope.org/mailman/listinfo/zope3-dev
 
-  Have fun!
+Have fun!
 
 Random Details
+==============
 
-    * There are some Python scripts in the top-level directory that
-      will help you track changes during the development process.
-      Specifically, 'setup.py' helps you build the extension modules,
-      and 'test.py' will run all of the unit tests (see UNITTEST.txt
-      in the doc directory for more information on unit tests).
+* There are some Python scripts in the top-level directory that will help you
+  track changes during the development process.  Specifically, 'setup.py'
+  helps you build the extension modules, and 'test.py' will run all of the
+  unit tests (see UNITTEST.txt in the doc directory for more information on
+  unit tests).
 
-    * You should be using Python 2.4.1 or later to run anything
-      related to Zope3.
+* You should be using Python 2.4.4 or later to run anything related to Zope 3.
 
-    * The Python you run Zope with *must* have threads compiled in.
-      This is typically the case for a vanilla build on platforms that
-      support thread, but be sure this wasn't disabled if you use a
-      custom build.  (If the Python statement "import thread" raises
-      an exception, your Python interpreter does not support threads.)
-      Warning: Zope will not run with a Python version that uses
-      libpth.  You *must* use libpthread.
+* The Python you run Zope with *must* have threads compiled in.  This is
+  typically the case for a vanilla build on platforms that support thread, but
+  be sure this wasn't disabled if you use a custom build.  (If the Python
+  statement "import thread" raises an exception, your Python interpreter does
+  not support threads.) Warning: Zope will not run with a Python version that
+  uses libpth.  You *must* use libpthread.
 
-    * To build Python extensions you need to have Python configuration
-      information available. If your Python comes from an RPM you may
-      need the python-devel package installed too. If you built Python
-      from source all the configuration information should already be
-      there.
+* To build Python extensions you need to have Python configuration information
+  available. If your Python comes from an RPM you may need the python-devel
+  package installed too. If you built Python from source all the configuration
+  information should already be there.
 
-    * If you just want to use Zope components it's not necessary to
-      build Zope but it's a good idea since it will compile Python C
-      extensions for you.
+* If you just want to use Zope components it's not necessary to build Zope but
+  it's a good idea since it will compile Python C extensions for you.
 
 Troubleshooting
+===============
 
-    * We've seen segfaults when running the test suite.  This was
-      invariably caused by having parts of Zope 2 or ZODB 3 (which
-      goes with Zope 2) installed in site-packages or elsewhere on
-      Python's module search path (sys.path).  So make sure you have
-      no parts of Zope 2 or ZODB 3 on sys.path when running Zope 3!
+* We've seen segfaults when running the test suite.  This was invariably
+  caused by having parts of Zope 2 or ZODB 3 (which goes with Zope 2)
+  installed in site-packages or elsewhere on Python's module search path
+  (sys.path).  So make sure you have no parts of Zope 2 or ZODB 3 on sys.path
+  when running Zope 3!

Modified: Zope3/trunk/doc/LOGGING.txt
===================================================================
--- Zope3/trunk/doc/LOGGING.txt	2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/LOGGING.txt	2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,145 +1,142 @@
+==============
 Zope 3 Logging
+==============
 
- Logging is done through the logging package (PEP 282-based logging).
- It is fairly easy to use and to configure.
+Logging is done through the logging package (PEP 282-based logging).  It is
+fairly easy to use and to configure.
 
+Configuring the logging package for z3.py
+=========================================
 
- Configuring the logging package for z3.py
+XXX This is out of date; see zope.conf.in for an example of the current way of
+configuring logging.
 
-  XXX This is out of date; see zope.conf.in for an example of the
-  current way of configuring logging.
+The log file used by z3.py can be configured in the zserver.zcml file with
+this directive::
 
-  The log file used by z3.py can be configured in the zserver.zcml
-  file with this directive::
-
     <startup:useLog file="..." level="...">
 
-  The file argument should give the filename where you want the log to
-  go.  If the filename is STDERR or STDOUT, logging goes to the
-  process's standard error or standard output stream, respectively.
+The file argument should give the filename where you want the log to go.  If
+the filename is STDERR or STDOUT, logging goes to the process's standard error
+or standard output stream, respectively.
 
-  The level argument should give the logging severity level; anything
-  below this level is not logged.  The supported levels are, in
-  increasing severity: DEBUG, INFO, WARN, ERROR, CRITICAL.
+The level argument should give the logging severity level; anything below this
+level is not logged.  The supported levels are, in increasing severity: DEBUG,
+INFO, WARN, ERROR, CRITICAL.
 
 
- Configuring the logging package for running unit tests
+Configuring the logging package for running unit tests
+======================================================
 
-  When running unit tests, logging is configured through the file
-  log.ini in the current directory, if it exists.  This file should be
-  self-explanatory, and provides full access to the logging package's
-  advanced features.  If log.ini is not found, critical messages are
-  logged to the process's standard error stream, and other messages
-  are not logged.
+When running unit tests, logging is configured through the file log.ini in the
+current directory, if it exists.  This file should be self-explanatory, and
+provides full access to the logging package's advanced features.  If log.ini
+is not found, critical messages are logged to the process's standard error
+stream, and other messages are not logged.
 
-  test.py also understands the LOGGING environment variable, which can
-  be used to specify an integer logging level.  So a simple way to run
-  the tests with all logging going to standard error is to set LOGGING
-  to 0, e.g.:
+test.py also understands the LOGGING environment variable, which can be used
+to specify an integer logging level.  So a simple way to run the tests with
+all logging going to standard error is to set LOGGING to 0, e.g.::
 
-  export LOGGING=0
-  python test.py
+    $ export LOGGING=0
+    $ python test.py
 
 
- Using the logging package
+Using the logging package
+=========================
 
-  There are two ways of using the logging package.  You can use
-  functions defined in the logging package directly, or you can use
-  methods on a logger object.  In either case you need a simple import
-  statement::
+There are two ways of using the logging package.  You can use functions
+defined in the logging package directly, or you can use methods on a logger
+object.  In either case you need a simple import statement::
 
-    import logging
+    >>> import logging
 
+Using the logging functions
+---------------------------
 
- Using the logging functions
+To use the logging functions defined by the package directly, use one of the
+functions debug(), info(), warn(), error() or critical() from the package.
+Each of these takes a message argument.  The message may be a standard Python
+format string, and then the following arguments are the format arguments.
+This allows you to write, for example::
 
-  To use the logging functions defined by the package directly, use
-  one of the functions debug(), info(), warn(), error() or critical()
-  from the package.  Each of these takes a message argument.  The
-  message may be a standard Python format string, and then the
-  following arguments are the format arguments.  This allows you to
-  write, for example::
+    >>> logging.warn("Cannot open file %r: %s", filename, err)
 
-    logging.warn("Cannot open file %r: %s", filename, err)
+instead of::
 
-  instead of::
+    >>> logging.warn("Cannot open file %r: %s" % (filename, err))
 
-    logging.warn("Cannot open file %r: %s" % (filename, err))
+Apart from slight savings in typing, the advantage of the former is that if
+warnings are not logged, the string formatting operation is not carried out,
+saving some time.
 
-  Apart from slight savings in typing, the advantage of the former is
-  that if warnings are not logged, the string formatting operation is
-  not carried out, saving some time.
+It is also possible to log a traceback.  This is done by adding a keyword
+argument exc_info=True.  For example::
 
-  It is also possible to log a traceback.  This is done by adding a
-  keyword argument exc_info=True.  For example::
+    >>> try:
+    ...     ...something...
+    ... except:
+    ...     logging.error("Unexpected problem", exc_info=True)
 
-    try:
-        ...something...
-    except:
-        logging.error("Unexpected problem", exc_info=True)
+The logging package will call sys.exc_info() and use the traceback module to
+format the traceback.  When the message is not logged, this is skipped.  In
+fact, there's a shorthand for this particular case (logging a traceback at the
+error level)::
 
-  The logging package will call sys.exc_info() and use the traceback
-  module to format the traceback.  When the message is not logged,
-  this is skipped.  In fact, there's a shorthand for this particular
-  case (logging a traceback at the error level)::
+    >>> try:
+    ...     ...something...
+    ... except:
+    ...     logging.exception("Unexpected problem")
 
-    try:
-        ...something...
-    except:
-        logging.exception("Unexpected problem")
+Finally, there is a generic log function; it has a first argument specifying a
+logging severity level, followed by the standard arguments of all the above
+functions::
 
-  Finally, there is a generic log function; it has a first argument
-  specifying a logging severity level, followed by the standard
-  arguments of all the above functions::
+    >>> logging.log(level, message, ..., exc_info=...)
 
-    logging.log(level, message, ..., exc_info=...)
+The predefined logging levels are available as symbolic constants:
+logging.DEBUG, logging.INFO, logging.WARN, logging.ERROR, and
+logging.CRITICAL.  (There's no logging.EXCEPTION level, because exception() is
+not a separate logging level; it's a shorthand for passing exc_info=True to
+the error() method.)
 
-  The predefined logging levels are available as symbolic constants:
-  logging.DEBUG, logging.INFO, logging.WARN, logging.ERROR, and
-  logging.CRITICAL.  (There's no logging.EXCEPTION level, because
-  exception() is not a separate logging level; it's a shorthand for
-  passing exc_info=True to the error() method.)
 
+Using a logger object
+---------------------
 
- Using a logger object
+Often you'd like all log messages coming out of a particular class or module
+to be "tagged" with a label identifying that class or module, regardless of
+the logging severity of the message.  In some cases, you'd like that label to
+convey additional run-time information, such as a storage or thread name.
 
-  Often you'd like all log messages coming out of a particular class
-  or module to be "tagged" with a label identifying that class or
-  module, regardless of the logging severity of the message.  In some
-  cases, you'd like that label to convey additional run-time
-  information, such as a storage or thread name.
+Rather than prefixing all log messages with an identifying string, you can
+create a logger object that does this for you.  Logger objects have methods
+debug(), info(), etc., corresponding to the logging functions described in the
+previous section, and with exactly the same signature; these are what you use
+to log a message using a logger object, for example::
 
-  Rather than prefixing all log messages with an identifying string,
-  you can create a logger object that does this for you.  Logger
-  objects have methods debug(), info(), etc., corresponding to the
-  logging functions described in the previous section, and with
-  exactly the same signature; these are what you use to log a message
-  using a logger object, for example::
+    >>> logger.warn("Oil temperature: %g", temp)
 
-    logger.warn("Oil temperature: %g", temp)
+To create a logger object, use the getLogger() function::
 
-  To create a logger object, use the getLogger() function::
+    >>> foo_bar_logger = logging.getLogger("foo.bar")
 
-    foo_bar_logger = logging.getLogger("foo.bar")
+The string argument to getLogger() is interpreted as a sequence of names
+separated by dots; this creates a hierarchy that can be used for additional
+filtering or handling.  Normally, however, a logger object inherits all its
+properties (except for its name) from its parent logger object.  For the
+foo_bar_logger above, the parent would be the logger object returned by this
+call::
 
-  The string argument to getLogger() is interpreted as a sequence of
-  names separated by dots; this creates a hierarchy that can be used
-  for additional filtering or handling.  Normally, however, a logger
-  object inherits all its properties (except for its name) from its
-  parent logger object.  For the foo_bar_logger above, the parent
-  would be the logger object returned by this call::
+    >>> foo_logger = logging.getLogger("foo")
 
-    foo_logger = logging.getLogger("foo")
+Its parent in turn is the root logger; the logging functions described in the
+previous section correspond to methods of the root logger object.  By
+configuring the root logger you can configure all loggers in the hierarchy,
+unless some configuration is overridden at a lower level.  This an advanced
+feature of the logging module that we won't discuss further here.
 
-  Its parent in turn is the root logger; the logging functions
-  described in the previous section correspond to methods of the root
-  logger object.  By configuring the root logger you can configure all
-  loggers in the hierarchy, unless some configuration is overridden at
-  a lower level.  This an advanced feature of the logging module that
-  we won't discuss further here.
-
-  Logger objects are lightweight and cached by the logging module;
-  subsequent calls to logging.getLogger() with the same logger name
-  will return the same logger object.  However, there is no way to
-  delete logger objects, so it's not a good idea to make up arbitrary
-  logger names dynamically.
+Logger objects are lightweight and cached by the logging module; subsequent
+calls to logging.getLogger() with the same logger name will return the same
+logger object.  However, there is no way to delete logger objects, so it's not
+a good idea to make up arbitrary logger names dynamically.

Modified: Zope3/trunk/doc/ROADMAP.txt
===================================================================
--- Zope3/trunk/doc/ROADMAP.txt	2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/ROADMAP.txt	2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,26 +1,14 @@
 Zope 3 Road Map
 ===============
 
-The Zope 3 release road map is pretty much dictated by the time-based
-release cycle.  There will be new major releases of Zope every six
-months (in June and December).
+The Zope 3 release road map is pretty much dictated by the time-based release
+cycle.  There will be new major releases of Zope every six months (in May and
+November).
 
-For a list of planned features please check TODOLATER.txt
+We are managing our bugs, todos and road map using Launchpad.
 
+Check out::
 
-Zope 3.2
---------
+    https://launchpad.net/zope3
 
-* Zope 3.2 alpha 1: mid-October, 2005
-
-* Zope 3.2 beta 1: first week in November, 2005
-
-* Zope 3.2 rc 1: mid-December, 2005
-
-* Zope 3.2 final: last week of December, 2005
-
-
-Zope 3.3
---------
-
-The release cycle will start in May, 2006
+for upcoming features and releases.

Modified: Zope3/trunk/doc/UNITTEST.txt
===================================================================
--- Zope3/trunk/doc/UNITTEST.txt	2007-04-16 07:07:24 UTC (rev 74164)
+++ Zope3/trunk/doc/UNITTEST.txt	2007-04-16 07:35:34 UTC (rev 74165)
@@ -1,240 +1,232 @@
+===================
 Zope 3 Unit Testing
+===================
 
- How to run Zope 3 unit tests
+How to run Zope 3 unit tests
+============================
 
-  In the top level directory, run "python test.py".  This runs all unit
-  tests silently (unless errors occur).  It is possible to run the
-  tests more verbosely or to be more selective about which tests to
-  run.  There are also other options.  For information about all this,
-  run "python test.py -h" which prints an extensive usage message.
+In the top level directory, run::
 
- Zope Testing
+    $ python test.py
 
-  If you encounter a directory named "tests" in a package within
-  within the Zope source code, it most likely indicates that the
-  directory contains test code used to ensure that the code owned by
-  the package works as it was designed.  Many of the test scripts
-  contained within Zope "tests" directories will be scripts which
-  contain "unit tests".
+This runs all unit tests silently (unless errors occur).  It is possible to
+run the tests more verbosely or to be more selective about which tests to run.
+There are also other options.  For information about all this, run "python
+test.py -h" which prints an extensive usage message.
 
- What Unit Tests Are
+Zope Testing
+============
 
-  A "unit" may be defined as a piece of code with a single intended
-  purpose.  A "unit test" is defined as a piece of code which exists
-  to codify the intended behavior of a unit and to compare its
-  intended behavior against its actual behavior.
+If you encounter a directory named "tests" in a package within within the Zope
+source code, it most likely indicates that the directory contains test code
+used to ensure that the code owned by the package works as it was designed.
 
-  Unit tests are a way for developers and quality assurance engineers
-  to quickly ascertain whether independent units of code are working as
-  expected.  Unit tests are generally written at the same time as the
-  code they are intended to test.  A unit testing framework allows a
-  collection of unit tests to be run without human intervention,
-  producing a minimum of output if all the tests in the collection are
-  successful.
 
- What Unit Tests Are Not
+What Unit Tests Are
+===================
 
-  It's very useful to define unit tests in terms of what they are
-  not.  From the "Extreme Programming Enthusiast" website
-  (http://c2.com/cgi/wiki?UnitTestsDefined)::
+A "unit" may be defined as a piece of code with a single intended purpose.  A
+"unit test" is defined as a piece of code which exists to codify the intended
+behavior of a unit and to compare its intended behavior against its actual
+behavior.
 
-   Unit tests are not:
+Unit tests are a way for developers and quality assurance engineers to quickly
+ascertain whether independent units of code are working as expected.  Unit
+tests are generally written at the same time as the code they are intended to
+test.  A unit testing framework allows a collection of unit tests to be run
+without human intervention, producing a minimum of output if all the tests in
+the collection are successful.
 
-    - Manually operated.
+What Unit Tests Are Not
+=======================
 
-    - Automated screen-driver tests that simulate user input (these
-      are "functional tests").
+It's very useful to define unit tests in terms of what they are not.  From the
+"Extreme Programming Enthusiast" website
+(http://c2.com/cgi/wiki?UnitTestsDefined)::
 
-    - Interactive.  They run "no questions asked."
+Unit tests are not:
 
-    - Coupled.  They run without dependencies except those native to
-      the thing being tested.
+- Manually operated.
 
-    - Complicated.  Unit test code is typically straightforward
-      procedural code that simulates an event.
+- Automated screen-driver tests that simulate user input (these are
+  "functional tests").
 
- Unit Testing Frameworks
+- Interactive.  They run "no questions asked."
 
-  A unit testing framework is generally employed to collect related
-  unit tests together in order to make it easier to run them as a
-  group.  When used with a unit testing framework, unit tests live
-  outside of the modules of code they're intended to test.
+- Coupled.  They run without dependencies except those native to the thing
+  being tested.
 
- How Unit Tests Help In The Development Process
+- Complicated.  Unit test code is typically straightforward procedural code
+  that simulates an event.
 
-  Unit tests should be written at the same time the code they test is
-  written.  A short, healthy cycle of "code/write test/run
-  test/repeat" can help a developer code more quickly by reducing
-  "backtracking" effort and by helping the developer focus on the
-  actual problem at hand.  Additionally, the unit tests generated at
-  initial development time can serve as later assurance that
-  maintenance and refactoring performed on code does not break any of
-  its intended functionality or behavior.  The results of unit tests
-  may additionally be used as a metric by quality assurance personnel
-  along with the results of other tests to gauge code quality before
-  before it is "shipped."
+Unit Testing Frameworks
+=======================
 
- Basic Unit Testing Philosophies
+A unit testing framework is generally employed to collect related unit tests
+together in order to make it easier to run them as a group.  When used with a
+unit testing framework, unit tests live outside of the modules of code they're
+intended to test.
 
-  Write unit tests at the same time that you write the code.
-  Nothing's worse than being faced with the prospect of writing tests
-  against a huge chunk of existing code because you "have to."
-  Writing unit tests post-facto can be boring and also robs you of the
-  main benefits that unit testing can provide.  Writing unit tests at
-  the same time you write the code helps you focus on the task at
-  hand.  Writing unit tests in conjunction with code can be fun and
-  satisfying, and can help you improve the quality of your code while
-  its goals are fresh in your mind.  Used properly, unit testing may
-  also help you write code faster, because you will need to
-  "backtrack" less.  Some "Extreme Programming" enthusiasts posit that
-  you should write a test before you write its associated code, and
-  then develop the code until it passes the test.
+How Unit Tests Help In The Development Process
+==============================================
 
-  Unit tests should be developed against as small and specific a
-  subset of a system's or subsystem's functionality as possible.  For
-  instance, a one unit test may test that a unique id generator
-  produces ids of a specific length, while another unit test in the
-  same group may ensure that a thousand ids from the same unique id
-  generator do not contain the same value.  Writing a single unit test
-  which tests a broad swath of a system's capabilities is
-  counterproductive, because it does not allow for a fine enough
-  granularity when attempting to figure out "what went wrong,"
-  requiring the developer to "backtrack".  Unit testing is capable of
-  helping to help reduce backtracking, but only if used properly.
+Unit tests should be written at the same time the code they test is written.
+A short, healthy cycle of "code/write test/run test/repeat" can help a
+developer code more quickly by reducing "backtracking" effort and by helping
+the developer focus on the actual problem at hand.  Additionally, the unit
+tests generated at initial development time can serve as later assurance that
+maintenance and refactoring performed on code does not break any of its
+intended functionality or behavior.  The results of unit tests may
+additionally be used as a metric by quality assurance personnel along with the
+results of other tests to gauge code quality before before it is "shipped."
 
-  A unit test does not produce any output unless it fails.  If a unit
-  test fails, it should print something useful, but short.  A unit
-  test should never fill the screen with output or otherwise produce
-  output that needs to be manually examined for "clues".  This is the
-  realm of other testing methodologies.  If unit tests are written at
-  sufficiently granular level, it is often enough just to know the
-  name of the unit test that failed.
+Basic Unit Testing Philosophies
+===============================
 
-  "It is better to have tried to test and failed than to not have
-  tried to test at all" aka "test the riskiest things first."  If the
-  prospect of writing a series of unit tests for an existing system
-  seems daunting, it's important to remember that no matter how many
-  unit tests you write, you cannot prove that your software does not
-  have bugs.  Therefore, you cannot possibly test every case while
-  developing.  You should plan to write tests against code based on
-  the risks involved in not testing that code.  Don't feel that you
-  need to write a test case for every "corner case" (although do try
-  to hit the riskiest ones).  In the worst case, it's better to have a
-  test module with one lonely unit test in it than none at all.
+Write unit tests at the same time that you write the code.  Nothing's worse
+than being faced with the prospect of writing tests against a huge chunk of
+existing code because you "have to." Writing unit tests post-facto can be
+boring and also robs you of the main benefits that unit testing can provide.
+Writing unit tests at the same time you write the code helps you focus on the
+task at hand.  Writing unit tests in conjunction with code can be fun and
+satisfying, and can help you improve the quality of your code while its goals
+are fresh in your mind.  Used properly, unit testing may also help you write
+code faster, because you will need to "backtrack" less.  Some "Extreme
+Programming" enthusiasts posit that you should write a test before you write
+its associated code, and then develop the code until it passes the test.
 
-  "Test fixtures" are employed by unit tests.  Test fixtures are bits
-  of state and environment that allow the unit test to perform its job
-  properly.  An example of a test fixture might be a file, an instance
-  of a class, or a row in a database table.  Any part of the
-  environment needed by a unit test besides the unit testing framework
-  itself is considered a test fixture.
+Unit tests should be developed against as small and specific a subset of a
+system's or subsystem's functionality as possible.  For instance, a one unit
+test may test that a unique id generator produces ids of a specific length,
+while another unit test in the same group may ensure that a thousand ids from
+the same unique id generator do not contain the same value.  Writing a single
+unit test which tests a broad swath of a system's capabilities is
+counterproductive, because it does not allow for a fine enough granularity
+when attempting to figure out "what went wrong," requiring the developer to
+"backtrack".  Unit testing is capable of helping to help reduce backtracking,
+but only if used properly.
 
-  In general, the common fixtures required by individual tests in a
-  testing group should be more or less identical.  If the fixtures
-  needed by a single test are radically different than the fixtures
-  required by the rest of the tests, or if the test does not require
-  the fixtures provided to the other tests, it probably belongs in
-  another (or its own) group of tests.
+A unit test does not produce any output unless it fails.  If a unit test
+fails, it should print something useful, but short.  A unit test should never
+fill the screen with output or otherwise produce output that needs to be
+manually examined for "clues".  This is the realm of other testing
+methodologies.  If unit tests are written at sufficiently granular level, it
+is often enough just to know the name of the unit test that failed.
 
-  When a unit test in a group modifies the state of a test fixture,
-  the test fixture should be restored to a known state before the next
-  unit test in the group is run.  Often, this means "rolling back"
-  changes to a transactional database or restoring the state of a
-  string so the next unit test can inherit a known state of the same
-  fixtures.  The unit testing framework has capabilities which allow
-  you to automate most of this work by providing a "set up" method
-  which gets called before each test is run and a "tear down" method
-  that gets called after a test is finished.
+"It is better to have tried to test and failed than to not have tried to test
+at all" aka "test the riskiest things first."  If the prospect of writing a
+series of unit tests for an existing system seems daunting, it's important to
+remember that no matter how many unit tests you write, you cannot prove that
+your software does not have bugs.  Therefore, you cannot possibly test every
+case while developing.  You should plan to write tests against code based on
+the risks involved in not testing that code.  Don't feel that you need to
+write a test case for every "corner case" (although do try to hit the riskiest
+ones).  In the worst case, it's better to have a test module with one lonely
+unit test in it than none at all.
 
-  Unit tests should play nicely with the unit testing framework they
-  employ.  Unit tests should not call "sys.exit()" or do similar
-  things which effect their ability to be run as part of a group of
-  tests.  The testing framework attempts to deal with misbehaved unit
-  tests, but it's better just to make them behave nicely in the first
-  place.
+"Test fixtures" are employed by unit tests.  Test fixtures are bits of state
+and environment that allow the unit test to perform its job properly.  An
+example of a test fixture might be a file, an instance of a class, or a row in
+a database table.  Any part of the environment needed by a unit test besides
+the unit testing framework itself is considered a test fixture.
 
-  Unit tests should "grow" with the code that they're intended to
-  test.  For example, if a group of unit tests is intended to verify
-  the behavior of all of the routines within a module, additional unit
-  tests should be added to the test group when new functionality is
-  added to that module.
+In general, the common fixtures required by individual tests in a testing
+group should be more or less identical.  If the fixtures needed by a single
+test are radically different than the fixtures required by the rest of the
+tests, or if the test does not require the fixtures provided to the other
+tests, it probably belongs in another (or its own) group of tests.
 
- Writing Unit Tests For The Zope Core
+When a unit test in a group modifies the state of a test fixture, the test
+fixture should be restored to a known state before the next unit test in the
+group is run.  Often, this means "rolling back" changes to a transactional
+database or restoring the state of a string so the next unit test can inherit
+a known state of the same fixtures.  The unit testing framework has
+capabilities which allow you to automate most of this work by providing a "set
+up" method which gets called before each test is run and a "tear down" method
+that gets called after a test is finished.
 
-  If you're not writing core code, you probably don't need to listen to
-  any more of this.  :-) The rules for writing tests for Zope core
-  code are simple:
+Unit tests should play nicely with the unit testing framework they employ.
+Unit tests should not call "sys.exit()" or do similar things which effect
+their ability to be run as part of a group of tests.  The testing framework
+attempts to deal with misbehaved unit tests, but it's better just to make them
+behave nicely in the first place.
 
-   - The testing code should make use of the standard Python unittest
-     module.  See the Python docs for usage information.
+Unit tests should "grow" with the code that they're intended to test.  For
+example, if a group of unit tests is intended to verify the behavior of all of
+the routines within a module, additional unit tests should be added to the
+test group when new functionality is added to that module.
 
-   - Tests must be placed in a "tests" subdirectory of the package or
-     directory in which the core code you're testing lives.
+Writing Unit Tests For The Zope Core
+====================================
 
-   - Test modules should be named something which represents the
-     functionality they test, and should begin with the prefix "test."
-     E.g., a test module for BTree should be named testBTree.py.
+If you're not writing core code, you probably don't need to listen to any more
+of this.  :-) The rules for writing tests for Zope core code are simple:
 
-   - An individual test module should take no longer than 60 seconds
-     to complete.
+- The testing code should make use of the standard Python unittest module.
+  See the Python docs for usage information.
 
-  more information available at http://dev.zope.org/Zope3/WritingUnitTests
+- Tests must be placed in a "tests" subdirectory of the package or directory
+  in which the core code you're testing lives.
 
- Writing Unit Tests For Applications Based On Zope
+- Test modules should be named something which represents the functionality
+  they test, and should begin with the prefix "test." E.g., a test module for
+  BTree should be named testBTree.py.
 
-  Zope uses the standard Python unittest module.  See the Python docs
-  for usage information.  You should establish your own conventions
-  for naming and placement of test modules.
+- An individual test module should take no longer than 60 seconds to complete.
 
-  Writing unit tests against applications based on Zope can be
-  difficult.  Zope is a collection of related modules, some with
-  non-trivial interdependencies.  Running its code successfully also
-  in some cases depends on state provided only in the context of a web
-  request, so calling Zope methods directly may not work as you
-  expect.  If you're not intimately familiar with Zope, implementing
-  unit tests can be frustrating.  For example, for the common case,
-  before you are able to write code which tests a Zope SQL Method, you
-  must establish a test fixture which represents your entire Zope
-  site.
+More information is available at::
 
-  Luckily, some tools are at your disposal to make writing unit tests
-  against Zope components and applications easier by making the
-  creation of these fixtures easier.
+    http://dev.zope.org/Zope3/WritingUnitTests
 
-  Surprisingly, one of the most effective tools for facilitating unit
-  testing is ZEO (http://www.zope.org/Products/ZEO).  ZEO is an
-  open-source clustering solution for Zope which makes it possible to
-  front-end a single "storage server" which manages a Zope object
-  database with multiple Zope clients that run a "client storage".
-  The reason ZEO is interesting for unit testing is mostly an
-  unintended side-effect of how it works as compared to Zope without
-  ZEO.  Zope without ZEO commonly uses a "FileStorage" to hold its
-  object database.  When Zope is started with a FileStorage, the
-  FileStorage code processes an "index" file.  This takes time.  Zope
-  using a ClientStorage as with ZEO does not process an index file,
-  making startup faster.  Fast startup of Zope is critical to
-  effective unit testing.  It is recommended that you implement ZEO if
-  you're heavy in to unit testing, as it really speeds things up.
-  It's not strictly required, however.
+Writing Unit Tests For Applications Based On Zope
+=================================================
 
- Administrivia
+Zope uses the standard Python unittest module.  See the Python docs for usage
+information.  You should establish your own conventions for naming and
+placement of test modules.
 
-  Unit test scripts found in the Zope source code is based on
-  the PyUnit unit testing framework, available from
-  http://pyunit.sourceforge.net, written by Stephen Purcell (thanks
-  Stephen!).  PyUnit is based on the JUnit testing framework for Java
-  (written by Kent Beck and Erich Gamma), which in turn was based on a
-  testing framework designed for Smalltalk (also written by Kent
-  Beck).
+Writing unit tests against applications based on Zope can be difficult.  Zope
+is a collection of related modules, some with non-trivial interdependencies.
+Running its code successfully also in some cases depends on state provided
+only in the context of a web request, so calling Zope methods directly may not
+work as you expect.  If you're not intimately familiar with Zope, implementing
+unit tests can be frustrating.  For example, for the common case, before you
+are able to write code which tests a Zope SQL Method, you must establish a
+test fixture which represents your entire Zope site.
 
-  Unit testing is a primary tenet of "Extreme Programming", a software
-  development methodology designed to facilitate the rapid production
-  of high quality code with a minimum of developmental ceremony.  For
-  more information on unit tests as they relate to Extreme
-  Programming, see http://c2.com/cgi/wiki?UnitTestsDefined.  Although
-  Digital Creations has not embraced the entire spectrum of Extreme
-  Programming methodologies in its software development process, we've
-  found unit tests a way to speed development and produce
-  higher-quality code.
+Luckily, some tools are at your disposal to make writing unit tests against
+Zope components and applications easier by making the creation of these
+fixtures easier.
 
+Surprisingly, one of the most effective tools for facilitating unit testing is
+ZEO (http://www.zope.org/Products/ZEO).  ZEO is an open-source clustering
+solution for Zope which makes it possible to front-end a single "storage
+server" which manages a Zope object database with multiple Zope clients that
+run a "client storage".  The reason ZEO is interesting for unit testing is
+mostly an unintended side-effect of how it works as compared to Zope without
+ZEO.  Zope without ZEO commonly uses a "FileStorage" to hold its object
+database.  When Zope is started with a FileStorage, the FileStorage code
+processes an "index" file.  This takes time.  Zope using a ClientStorage as
+with ZEO does not process an index file, making startup faster.  Fast startup
+of Zope is critical to effective unit testing.  It is recommended that you
+implement ZEO if you're heavy in to unit testing, as it really speeds things
+up.  It's not strictly required, however.
 
+Administrivia
+=============
+
+Unit test scripts found in the Zope source code are based on the PyUnit unit
+testing framework, available from http://pyunit.sourceforge.net, written by
+Stephen Purcell (thanks Stephen!).  PyUnit is based on the JUnit testing
+framework for Java (written by Kent Beck and Erich Gamma), which in turn was
+based on a testing framework designed for Smalltalk (also written by Kent
+Beck).
+
+Unit testing is a primary tenet of "Extreme Programming", a software
+development methodology designed to facilitate the rapid production of high
+quality code with a minimum of developmental ceremony.  For more information
+on unit tests as they relate to Extreme Programming, see
+http://c2.com/cgi/wiki?UnitTestsDefined.  Although Digital Creations has not
+embraced the entire spectrum of Extreme Programming methodologies in its
+software development process, we've found unit tests a way to speed
+development and produce higher-quality code.



More information about the Zope3-Checkins mailing list