Deprecate nova.hooks

This emits a warning message when hooks are used to ensure that admins
understand that this facility is deprecated in Nova going forward. It
also removes the links to the meager documentation on hooks to ensure
no one finds these by accident and starts using them. Also add a
comment to the code file itself incase someone ends up in it from
other searches.

Change-Id: I31b1223a0dc3fdffe356a816b591fdd88a31483a

doc/source/hooks.rst

@@ -1,57 +0,0 @@
-Hooks
-=====
-
-Hooks provide a mechanism to extend Nova with custom code through a plugin
-mechanism.
-
-Named hooks are added to nova code via a decorator that will lazily load
-plugin code matching the name.  The loading works via setuptools
-`entry points`_.
-
-.. _`entry points`: http://pythonhosted.org/setuptools/pkg_resources.html#entry-points
-
-What are hooks good for?
-------------------------
-
-Hooks are good for anchoring your custom code to Nova internal APIs.
-
-What are hooks NOT good for?
-----------------------------
-
-Hooks should not be used when API stability is a key factor.  Internal APIs may
-change.  Consider using a notification driver if this is important to you.
-
-Declaring hooks in the Nova codebase
-------------------------------------
-
-The following example declares a *resize_hook* around the *resize_instance* method::
-
-    from nova import hooks
-
-    @hooks.add_hook("resize_hook")
-    def resize_instance(self, context, instance, a=1, b=2):
-        ...
-
-Hook objects can now be attached via entry points to the *resize_hook*.
-
-Adding hook object code
------------------------
-
-1. Setup a Python package with a setup.py file.
-2. Add the following to the setup.py setup call::
-
-    entry_points = {
-        'nova.hooks': [
-            'resize_hook=your_package.hooks:YourHookClass',
-        ]
-    },
-
-3. *YourHookClass* should be an object with *pre* and/or *post* methods::
-
-    class YourHookClass(object):
-
-        def pre(self, *args, **kwargs):
-            ....
-
-        def post(self, rv, *args, **kwargs):
-            ....

doc/source/index.rst

@@ -153,7 +153,6 @@ Open Development.
    i18n
    filter_scheduler
    rpc
-   hooks
    block_device_mapping
    addmethod.openstackapi
    conductor

nova/hooks.py

@@ -16,6 +16,9 @@
 """Decorator and config option definitions for adding custom code (hooks)
 around callables.
 
+NOTE: as of Nova 13.0 hooks are DEPRECATED and will be removed in the
+near future. You should not build any new code using this facility.
+
 Any method may have the 'add_hook' decorator applied, which yields the
 ability to invoke Hook objects before or after the method. (i.e. pre and
 post)
@@ -47,7 +50,7 @@ import functools
 from oslo_log import log as logging
 import stevedore
 
-from nova.i18n import _, _LE
+from nova.i18n import _, _LE, _LW
 
 LOG = logging.getLogger(__name__)
 NS = 'nova.hooks'
@@ -82,6 +85,8 @@ class HookManager(stevedore.hook.HookManager):
             obj = e.obj
             hook_method = getattr(obj, method_type, None)
             if hook_method:
+                LOG.warning(_LW("Hooks are deprecated as of Nova 13.0 and "
+                                "will be removed in a future release"))
                 LOG.debug("Running %(name)s %(type)s-hook: %(obj)s",
                           {'name': name, 'type': method_type, 'obj': obj})
                 try:

releasenotes/notes/deprecate_hooks-6f6d60ac206a6da6.yaml

@@ -0,0 +1,7 @@
+---
+deprecations:
+  - Deprecate the use of nova.hooks. This facility used to let
+    arbitrary out of tree code be executed around certain internal
+    actions, but is unsuitable for having a well maintained
+    API. Anyone using this facility should bring forward their use
+    cases in the Newton cycle as nova-specs.