From 23b5806932cf0c890a8ba665148abeb5dce53755 Mon Sep 17 00:00:00 2001 From: Ihar Hrachyshka Date: Thu, 2 Jul 2015 18:32:42 +0300 Subject: [PATCH] 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 --- doc/source/devref/index.rst | 1 + doc/source/devref/neutron_api.rst | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 doc/source/devref/neutron_api.rst diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst index d2b263baa..d54d44269 100644 --- 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 index 000000000..92e116d25 --- /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. -- 2.45.2