Effective: avoid mocking open() if you can

Change-Id: Idcf1d1a410be10c5a557ab89a5dc83e3649cd086

diff --git a/doc/source/devref/effective_neutron.rst b/doc/source/devref/effective_neutron.rst
index 8b7981b118c9126110051307347bb412060f02c0..0fd55d4cf63829533260cd8375f0a8c8d02b8485 100644 (file)
--- a/doc/source/devref/effective_neutron.rst
+++ b/doc/source/devref/effective_neutron.rst
@@ -155,6 +155,14 @@ For anything more elaborate, please visit the testing section.
 * Don't mimic existing tests that violate these guidelines. We are attempting to
   replace all of these so more tests like them create more work. If you need help
   writing a test, reach out to the testing lieutenants and the team on IRC.
+* Mocking open() is a dangerous practice because it can lead to unexpected
+  bugs like `bug 1503847 <https://bugs.launchpad.net/neutron/+bug/1503847>`_.
+  In fact, when the built-in open method is mocked during tests, some
+  utilities (like debtcollector) may still rely on the real thing, and may
+  end up using the mock rather what they are really looking for. If you must,
+  consider scoping by `module https://review.openstack.org/#/c/232265/`_, but
+  it is better not to mock open() at all.
+
 
 Backward compatibility
 ~~~~~~~~~~~~~~~~~~~~~~