plugin.py: Add API to allow plugins to raise deprecation warningsphil/848-plugin-deprecation-warnings

A plugin's deprecation warning may be silenced by a project by adding
the plugin to the list 'supress-deprecation-warnings' in the project's
project.conf

7 files changed, 130 insertions, 1 deletions

diff --git a/buildstream/_versions.py b/buildstream/_versions.py
index a9eb86d69..5affc7870 100644
--- a/buildstream/_versions.py
+++ b/buildstream/_versions.py
@@ -23,7 +23,7 @@
 # This version is bumped whenever enhancements are made
 # to the `project.conf` format or the core element format.
 #
-BST_FORMAT_VERSION = 21
+BST_FORMAT_VERSION = 22
 
 
 # The base BuildStream artifact version
diff --git a/buildstream/plugin.py b/buildstream/plugin.py
index 2f51c8807..c21ae939e 100644
--- a/buildstream/plugin.py
+++ b/buildstream/plugin.py
@@ -164,6 +164,25 @@ class Plugin():
        core format version :ref:`core format version <project_format_version>`.
     """
 
+    BST_PLUGIN_DEPRECATED = False
+    """True if this element plugin has been deprecated.
+
+    If this is set to true, BuildStream will emmit a deprecation
+    warning when this plugin is loaded. This deprecation warning may
+    be suppressed on a plugin by plugin basis by setting
+    ``suppress-deprecation-warnings: true`` in the relevent section of
+    the project's :ref:`plugin configuration overrides <project_overrides>`.
+
+    """
+
+    BST_PLUGIN_DEPRECATION_MESSAGE = ""
+    """ The message printed when this element shows a deprecation warning.
+
+    This should be set if BST_PLUGIN_DEPRECATED is True and should direct the user
+    to the deprecated plug-in's replacement.
+
+    """
+
     def __init__(self, name, context, project, provenance, type_tag):
 
         self.name = name
@@ -188,6 +207,12 @@ class Plugin():
         self.__kind = modulename.split('.')[-1]
         self.debug("Created: {}".format(self))
 
+        # If this plugin has been deprecated, emit a warning.
+        if self.BST_PLUGIN_DEPRECATED and not self.__deprecation_warning_silenced():
+            detail = "Using deprecated plugin {}: {}".format(self.__kind,
+                                                             self.BST_PLUGIN_DEPRECATION_MESSAGE)
+            self.__message(MessageType.WARN, detail)
+
     def __del__(self):
         # Dont send anything through the Message() pipeline at destruction time,
         # any subsequent lookup of plugin by unique id would raise KeyError.
@@ -767,6 +792,20 @@ class Plugin():
         else:
             return self.name
 
+    def __deprecation_warning_silenced(self):
+        if not self.BST_PLUGIN_DEPRECATED:
+            return False
+        else:
+            silenced_warnings = set()
+            project = self.__project
+            plugin_overrides = {**project.element_overrides, **project.source_overrides}
+
+            for key, value in self.node_items(plugin_overrides):
+                if value.get('suppress-deprecation-warnings', False):
+                    silenced_warnings.add(key)
+
+            return self.get_kind() in silenced_warnings
+
 
 # Hold on to a lookup table by counter of all instantiated plugins.
 # We use this to send the id back from child processes so we can lookup
diff --git a/tests/plugins/deprecationwarnings/deprecationwarnings.py b/tests/plugins/deprecationwarnings/deprecationwarnings.py
new file mode 100644
index 000000000..799f162dc
--- /dev/null
+++ b/tests/plugins/deprecationwarnings/deprecationwarnings.py
@@ -0,0 +1,41 @@
+import pytest
+import tempfile
+import os
+from buildstream.plugintestutils import cli
+from buildstream import _yaml
+import buildstream.plugins.elements.manual
+
+
+DATA_DIR = os.path.join(
+    os.path.dirname(os.path.realpath(__file__)),
+    "project"
+)
+
+_DEPRECATION_MESSAGE = "Here is some detail."
+_DEPRECATION_WARNING = "Using deprecated plugin deprecated_plugin: {}".format(_DEPRECATION_MESSAGE)
+
+
+@pytest.mark.datafiles(DATA_DIR)
+def test_deprecation_warning_present(cli, datafiles):
+    project = os.path.join(datafiles.dirname, datafiles.basename)
+    result = cli.run(project=project, args=['show', 'deprecated.bst'])
+    result.assert_success()
+    assert _DEPRECATION_WARNING in result.stderr
+
+
+@pytest.mark.datafiles(DATA_DIR)
+def test_suppress_deprecation_warning(cli, datafiles):
+    project = os.path.join(datafiles.dirname, datafiles.basename)
+    result = cli.run(project=project, args=['show', 'manual.bst'])
+
+    element_overrides = "elements:\n" \
+                        "  deprecated_plugin:\n" \
+                        "    suppress-deprecation-warnings : True\n"
+
+    project_conf = os.path.join(project, 'project.conf')
+    with open(project_conf, 'a') as f:
+        f.write(element_overrides)
+
+    result = cli.run(project=project, args=['show', 'deprecated.bst'])
+    result.assert_success()
+    assert _DEPRECATION_WARNING not in result.stderr
diff --git a/tests/plugins/deprecationwarnings/project/elements/deprecated.bst b/tests/plugins/deprecationwarnings/project/elements/deprecated.bst
new file mode 100644
index 000000000..e80bd91cd
--- /dev/null
+++ b/tests/plugins/deprecationwarnings/project/elements/deprecated.bst
@@ -0,0 +1 @@
+kind: deprecated_plugin
\ No newline at end of file
diff --git a/tests/plugins/deprecationwarnings/project/plugins/elements/deprecated_plugin.py b/tests/plugins/deprecationwarnings/project/plugins/elements/deprecated_plugin.py
new file mode 100644
index 000000000..a8e39562a
--- /dev/null
+++ b/tests/plugins/deprecationwarnings/project/plugins/elements/deprecated_plugin.py
@@ -0,0 +1,11 @@
+from buildstream import BuildElement, SandboxFlags
+
+
+class DeprecatedPlugin(BuildElement):
+    BST_PLUGIN_DEPRECATED = True
+    BST_PLUGIN_DEPRECATION_MESSAGE = "Here is some detail."
+
+
+# Plugin entry point
+def setup():
+    return DeprecatedPlugin
diff --git a/tests/plugins/deprecationwarnings/project/plugins/elements/deprecated_plugin.yaml b/tests/plugins/deprecationwarnings/project/plugins/elements/deprecated_plugin.yaml
new file mode 100644
index 000000000..1c07cd8b2
--- /dev/null
+++ b/tests/plugins/deprecationwarnings/project/plugins/elements/deprecated_plugin.yaml
@@ -0,0 +1,22 @@
+# Deprecated-plugin build element does not provide any default
+# build commands
+config:
+
+  # Commands for configuring the software
+  #
+  configure-commands: []
+
+  # Commands for building the software
+  #
+  build-commands: []
+
+  # Commands for installing the software into a
+  # destination folder
+  #
+  install-commands: []
+
+  # Commands for stripping installed binaries
+  #
+  strip-commands:
+  - |
+    %{strip-binaries}
\ No newline at end of file
diff --git a/tests/plugins/deprecationwarnings/project/project.conf b/tests/plugins/deprecationwarnings/project/project.conf
new file mode 100644
index 000000000..18e368fe9
--- /dev/null
+++ b/tests/plugins/deprecationwarnings/project/project.conf
@@ -0,0 +1,15 @@
+# Unique project name
+name: deprecation-warnings
+
+# Required BuildStream format version
+format-version: 20
+
+# Subdirectory where elements are stored
+element-path: elements
+
+plugins:
+
+- origin: local
+  path: plugins/elements
+  elements:
+    deprecated_plugin: 0