devref: document API status for neutron.openstack.common.*

Make sure we document the fact that neutron.openstack.common.* contents
are not meant to be used by external repositories (except, temporarily,
*aas repos).

If I could bootstrap the oslo-incubator subtree from scratch, I would
put it under neutron._openstack, to indicate that it's for internal
usage only. But we can't do it now, so instead I update devref.

Change-Id: I42252a7b0a07759c57995b2fc1f8d20ecba7d33b

diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst
index d2b263baa5f7fa6c6791ec3f0d33b322da704115..d54d442697db6c2d271403ca865c8b97547c6c40 100644 (file)
--- a/doc/source/devref/index.rst
+++ b/doc/source/devref/index.rst
@@ -32,6 +32,7 @@ Programming HowTos and Tutorials
 
     development.environment
     contribute
+    neutron_api
     sub_projects
 
 

diff --git a/doc/source/devref/neutron_api.rst b/doc/source/devref/neutron_api.rst
new file mode 100644 (file)
index 0000000..92e116d
--- /dev/null
+++ b/doc/source/devref/neutron_api.rst
@@ -0,0 +1,20 @@
+Neutron public API
+==================
+
+Neutron main tree serves as a library for multiple subprojects that rely on
+different modules from neutron.* namespace to accomodate their needs.
+Specifically, advanced service repositories and open source or vendor
+plugin/driver repositories do it.
+
+Neutron modules differ in their API stability a lot, and there is no part of it
+that is explicitly marked to be consumed by other projects.
+
+That said, there are modules that other projects should definitely avoid relying on.
+
+Specifically, no external repository should use anything located under
+neutron.openstack.common.* import path. This code belongs to oslo-incubator
+modules and is not meant to work for consumers other than neutron main tree
+itself. (The only exception is made for advanced service repositories that are
+tightly controlled by neutron community.) Long story short, if your repository
+uses those modules, please switch to corresponding oslo libraries or use your
+own copy of oslo-incubator files.