bump version number, refine goodpractises wrt to importing test modules

CHANGELOG

@@ -1,4 +1,4 @@
-Changes between 2.1.0 and 2.1.1.DEV
+Changes between 2.1.0 and 2.1.1
 ----------------------------------------------
 
 - fix error conditions involving the creation of __pycache__

_pytest/__init__.py

@@ -1,2 +1,2 @@
 #
-__version__ = '2.1.1.dev4'
+__version__ = '2.1.1.dev5'

doc/goodpractises.txt

@@ -53,7 +53,7 @@ You can tell people to download the script and then e.g.  run it like this::
 Integrating with distutils / ``python setup.py test``
 --------------------------------------------------------
 
-You can easily integrate test runs into your distutils or
+You can integrate test runs into your distutils or
 setuptools based project.  Use the `genscript method`_
 to generate a standalone py.test script::
 
@@ -106,9 +106,9 @@ Conventions for Python test discovery
 * ``Test`` prefixed test classes (without an ``__init__`` method)
 * ``test_`` prefixed test functions or methods are test items
 
-For examples of how to cnd cusotmize your test discovery :doc:`example/pythoncollection`.
+For examples of how to customize your test discovery :doc:`example/pythoncollection`.
 
-py.test additionally discovers tests using the standard
+Within Python modules, py.test also discovers tests using the standard
 :ref:`unittest.TestCase <unittest.TestCase>` subclassing technique.
 
 Choosing a test layout / import rules
@@ -138,7 +138,10 @@ py.test supports common test layouts:
         test_app.py
         ...
 
-You can always run your tests by pointing to it::
+In both cases you usually need to make sure that ``mypkg`` is importable,
+for example by using the setuptools ``python setup.py develop`` method.
+
+You can run your tests by pointing to it::
 
     py.test tests/test_app.py       # for external test dirs
     py.test mypkg/test/test_app.py  # for inlined test dirs
@@ -150,18 +153,27 @@ You can always run your tests by pointing to it::
 
 .. note::
 
-    Test modules are imported under their fully qualified name as follows:
+    If py.test finds a "a/b/test_module.py" test file while
+    recursing into the filesystem it determines the import name
+    as follows:
 
     * find ``basedir`` -- this is the first "upward" (towards the root)
-      directory not containing an ``__init__.py``
+      directory not containing an ``__init__.py``.  If both the ``a``
+      and ``b`` directories contain an ``__init__.py`` the basedir will 
+      be the parent dir of ``a``.
 
-    * perform ``sys.path.insert(0, basedir)`` to make the fully
+    * perform ``sys.path.insert(0, basedir)`` to make the test module
-      qualified test module path importable.
+      importable under the fully qualified import name.
 
-    * ``import path.to.test_module`` where the path is determined
+    * ``import a.b.test_module`` where the path is determined
-      by converting path separators into "." files.  This means
+      by converting path separators ``/`` into "." characters.  This means
       you must follow the convention of having directory and file
-      names map to the import names.
+      names map directly to the import names.
+
+    The reason for this somewhat evolved importing technique is
+    that in larger projects multiple test modules might import
+    from each other and thus deriving a canonical import name helps
+    to avoid surprises such as a test modules getting imported twice.
 
 
 .. include:: links.inc

setup.py

@@ -24,7 +24,7 @@ def main():
         name='pytest',
         description='py.test: simple powerful testing with Python',
         long_description = long_description,
-        version='2.1.1.dev4',
+        version='2.1.1.dev5',
         url='http://pytest.org',
         license='MIT license',
         platforms=['unix', 'linux', 'osx', 'cygwin', 'win32'],