From 7be56442703d071c9256267abb8acfabae642a1a Mon Sep 17 00:00:00 2001
From: Sean Dague <sean@dague.net>
Date: Mon, 29 Feb 2016 15:49:20 -0500
Subject: [PATCH] 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                          | 57 -------------------
 doc/source/index.rst                          |  1 -
 nova/hooks.py                                 |  7 ++-
 .../deprecate_hooks-6f6d60ac206a6da6.yaml     |  7 +++
 4 files changed, 13 insertions(+), 59 deletions(-)
 delete mode 100644 doc/source/hooks.rst
 create mode 100644 releasenotes/notes/deprecate_hooks-6f6d60ac206a6da6.yaml

diff --git a/doc/source/hooks.rst b/doc/source/hooks.rst
deleted file mode 100644
index 5d6b09d2e94b..000000000000
--- a/doc/source/hooks.rst
+++ /dev/null
@@ -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):
-            ....
diff --git a/doc/source/index.rst b/doc/source/index.rst
index abb09e252138..4e630a5ee4d0 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -153,7 +153,6 @@ Open Development.
    i18n
    filter_scheduler
    rpc
-   hooks
    block_device_mapping
    addmethod.openstackapi
    conductor
diff --git a/nova/hooks.py b/nova/hooks.py
index 35bc3af29d49..bb85f38ee994 100644
--- a/nova/hooks.py
+++ b/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:
diff --git a/releasenotes/notes/deprecate_hooks-6f6d60ac206a6da6.yaml b/releasenotes/notes/deprecate_hooks-6f6d60ac206a6da6.yaml
new file mode 100644
index 000000000000..6990935e7d06
--- /dev/null
+++ b/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.