Provide pointer for ML2 extension manager to effective guide

This is sorely missed in the devref. More content should be
added. Hint hint.

Change-Id: If8a7e98a9ebd6b4fe7effa6c577ea818c63d8d85

diff --git a/doc/source/devref/effective_neutron.rst b/doc/source/devref/effective_neutron.rst
index bbe918189ec3bb1ae5361323caab2946c47b56f9..b38af7089d200ff7cab5e7472deb7664d3ffb285 100644 (file)
--- a/doc/source/devref/effective_neutron.rst
+++ b/doc/source/devref/effective_neutron.rst
@@ -63,6 +63,8 @@ Document common pitfalls as well as good practices done during plugin developmen
   but their strength is also a weakness, as they can introduce `unpredictable <https://review.openstack.org/#/c/121290/>`_
   behavior to the `MRO <https://www.python.org/download/releases/2.3/mro/>`_,
   amongst other issues.
+* In lieu of mixins, if you need to add behavior that is relevant for ML2,
+  consider using the `extension manager <http://specs.openstack.org/openstack/neutron-specs/specs/juno/neutron-ml2-mechanismdriver-extensions.html>`_.
 * If you make changes to the DB class methods, like calling methods that can
   be inherited, think about what effect that may have to plugins that have
   controller `backends <https://review.openstack.org/#/c/116924/>`_.

diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst
index 8c4718ad5744b95b3ea3405c1d308bdfcd096e5d..d72bdadcb0a1225c70b19cf35d3eaeedd3cafb88 100644 (file)
--- a/doc/source/devref/index.rst
+++ b/doc/source/devref/index.rst
@@ -54,6 +54,7 @@ Neutron Internals
 
    services_and_agents
    api_layer
+   ml2_ext_manager
    quota
    api_extensions
    plugin-api

diff --git a/doc/source/devref/ml2_ext_manager.rst b/doc/source/devref/ml2_ext_manager.rst
new file mode 100644 (file)
index 0000000..9f82784
--- /dev/null
+++ b/doc/source/devref/ml2_ext_manager.rst
@@ -0,0 +1,31 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+
+ML2 Extension Manager
+=====================
+
+The extension manager for ML2 was introduced in Juno (more details
+can be found in the approved `spec <http://specs.openstack.org/openstack/neutron-specs/specs/juno/neutron-ml2-mechanismdriver-extensions.html>`_). The features allows for extending ML2 resources without
+actually having to introduce cross cutting concerns to ML2. The
+mechanism has been applied for a number of use cases, and extensions
+that currently use this frameworks are available under `ml2/extensions <https://github.com/openstack/neutron/tree/master/neutron/plugins/ml2/extensions>`_.