From 8e6d538a572291d6269ba2fe9917ec8041b8eaee Mon Sep 17 00:00:00 2001
From: holger krekel <holger@merlinux.eu>
Date: Thu, 23 Jan 2014 15:25:01 +0100
Subject: [PATCH] address issue416: clarify docs as to conftest.py loading
 semantics

---
 CHANGELOG          |  3 +++
 doc/en/plugins.txt | 12 +++++++++---
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index b0148b4f5..6d477374a 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -15,6 +15,9 @@ UNRELEASED
   correctly also on python2 and with pytest-xdist runs. (the fix
   requires py-1.4.20)
 
+- address issue416: clarify docs as to conftest.py loading semantics
+
+
 2.5.1
 -----------------------------------
 
diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt
index a14478978..0f612cceb 100644
--- a/doc/en/plugins.txt
+++ b/doc/en/plugins.txt
@@ -177,9 +177,15 @@ Plugin discovery order at tool startup
   and loading the specified plugin before actual command line parsing.
 
 * by loading all :file:`conftest.py` files as inferred by the command line
-  invocation (test files and all of its *parent* directories).
-  Note that ``conftest.py`` files from *sub* directories are by default
-  not loaded at tool startup.
+  invocation:
+
+  - if no test paths are specified use current dir as a test path
+  - if exists, load ``conftest.py`` and ``test*/conftest.py`` relative 
+    to the directory part of the first test path. 
+
+  Note that pytest does not find ``conftest.py`` files in deeper nested
+  sub directories at tool startup.  It is usually a good idea to keep
+  your conftest.py file in the top level test or project root directory.
 
 * by recursively loading all plugins specified by the
   ``pytest_plugins`` variable in ``conftest.py`` files