plugin.py: Rework how deprecation warnings are configured.

This is mostly a semantic change which defines how deprecation warnings
are suppressed in a more consistent fashion, by declaring such suppressions
in the plugin origin declarations rather than on the generic element/source
configuration overrides section.

Other side effects of this commit are that the warnings have been enhanced
to include the provenance of whence the deprecated plugins have been used in
the project, and that the custom deprecation message is optional and will
appear in the message detail string rather than in the primary warning text,
which now simply indicates that the plugin being used is deprecated.

Documentation and test cases are updated.

This fixes #1291

8 files changed, 128 insertions, 88 deletions

diff --git a/tests/plugins/deprecationwarnings.py b/tests/plugins/deprecationwarnings.py
deleted file mode 100644
index a4da3ea72..000000000
--- a/tests/plugins/deprecationwarnings.py
+++ /dev/null
@@ -1,38 +0,0 @@
-# Pylint doesn't play well with fixtures and dependency injection from pytest
-# pylint: disable=redefined-outer-name
-
-import os
-
-import pytest
-
-from buildstream.testing import cli  # pylint: disable=unused-import
-
-
-DATA_DIR = os.path.join(os.path.dirname(os.path.realpath(__file__)), "deprecationwarnings")
-
-_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 = str(datafiles)
-    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 = str(datafiles)
-    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/elements/deprecated.bst b/tests/plugins/deprecationwarnings/elements/deprecated.bst
deleted file mode 100644
index e80bd91cd..000000000
--- a/tests/plugins/deprecationwarnings/elements/deprecated.bst
+++ /dev/null
@@ -1 +0,0 @@
-kind: deprecated_plugin
\ No newline at end of file
diff --git a/tests/plugins/deprecationwarnings/plugins/elements/deprecated_plugin.py b/tests/plugins/deprecationwarnings/plugins/elements/deprecated_plugin.py
deleted file mode 100644
index 244009764..000000000
--- a/tests/plugins/deprecationwarnings/plugins/elements/deprecated_plugin.py
+++ /dev/null
@@ -1,12 +0,0 @@
-from buildstream import BuildElement
-
-
-class DeprecatedPlugin(BuildElement):
-    BST_MIN_VERSION = "2.0"
-    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/plugins/elements/deprecated_plugin.yaml b/tests/plugins/deprecationwarnings/plugins/elements/deprecated_plugin.yaml
deleted file mode 100644
index 1c07cd8b2..000000000
--- a/tests/plugins/deprecationwarnings/plugins/elements/deprecated_plugin.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# 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.conf b/tests/plugins/deprecationwarnings/project.conf
deleted file mode 100644
index 9e03afe0a..000000000
--- a/tests/plugins/deprecationwarnings/project.conf
+++ /dev/null
@@ -1,15 +0,0 @@
-# Unique project name
-name: deprecation-warnings
-
-# Required BuildStream version
-min-version: 2.0
-
-# Subdirectory where elements are stored
-element-path: elements
-
-plugins:
-
-- origin: local
-  path: plugins/elements
-  elements:
-  - deprecated_plugin
diff --git a/tests/plugins/loading.py b/tests/plugins/loading.py
index a54df776e..152f4080b 100644
--- a/tests/plugins/loading.py
+++ b/tests/plugins/loading.py
@@ -230,3 +230,76 @@ def test_plugin_found(cli, datafiles, plugin_type):
 
     result = cli.run(project=project, args=["show", "element.bst"])
     result.assert_success()
+
+
+@pytest.mark.datafiles(DATA_DIR)
+@pytest.mark.parametrize("plugin_type", [("elements"), ("sources")])
+def test_deprecation_warnings(cli, datafiles, plugin_type):
+    project = str(datafiles)
+
+    update_project(
+        project,
+        {
+            "plugins": [
+                {
+                    "origin": "local",
+                    "path": os.path.join("plugins", plugin_type, "deprecated"),
+                    plugin_type: ["deprecated"],
+                }
+            ]
+        },
+    )
+    setup_element(project, plugin_type, "deprecated")
+
+    result = cli.run(project=project, args=["show", "element.bst"])
+    result.assert_success()
+    assert "Here is some detail." in result.stderr
+
+
+@pytest.mark.datafiles(DATA_DIR)
+@pytest.mark.parametrize("plugin_type", [("elements"), ("sources")])
+def test_deprecation_warning_suppressed_by_origin(cli, datafiles, plugin_type):
+    project = str(datafiles)
+
+    update_project(
+        project,
+        {
+            "plugins": [
+                {
+                    "origin": "local",
+                    "path": os.path.join("plugins", plugin_type, "deprecated"),
+                    "allow-deprecated": True,
+                    plugin_type: ["deprecated"],
+                }
+            ]
+        },
+    )
+    setup_element(project, plugin_type, "deprecated")
+
+    result = cli.run(project=project, args=["show", "element.bst"])
+    result.assert_success()
+    assert "Here is some detail." not in result.stderr
+
+
+@pytest.mark.datafiles(DATA_DIR)
+@pytest.mark.parametrize("plugin_type", [("elements"), ("sources")])
+def test_deprecation_warning_suppressed_specifically(cli, datafiles, plugin_type):
+    project = str(datafiles)
+
+    update_project(
+        project,
+        {
+            "plugins": [
+                {
+                    "origin": "local",
+                    "path": os.path.join("plugins", plugin_type, "deprecated"),
+                    plugin_type: [{"kind": "deprecated", "allow-deprecated": True}],
+                }
+            ]
+        },
+    )
+    setup_element(project, plugin_type, "deprecated")
+
+    result = cli.run(project=project, args=["show", "element.bst"])
+    result.assert_success()
+    assert "Here is some detail." not in result.stderr
diff --git a/tests/plugins/loading/plugins/elements/deprecated/deprecated.py b/tests/plugins/loading/plugins/elements/deprecated/deprecated.py
new file mode 100644
index 000000000..7184710bc
--- /dev/null
+++ b/tests/plugins/loading/plugins/elements/deprecated/deprecated.py
@@ -0,0 +1,21 @@
+from buildstream import Element
+
+
+class Deprecated(Element):
+    BST_MIN_VERSION = "2.0"
+    BST_PLUGIN_DEPRECATED = True
+    BST_PLUGIN_DEPRECATION_MESSAGE = "Here is some detail."
+
+    def configure(self, node):
+        pass
+
+    def preflight(self):
+        pass
+
+    def get_unique_key(self):
+        return {}
+
+
+# Plugin entry point
+def setup():
+    return Deprecated
diff --git a/tests/plugins/loading/plugins/sources/deprecated/deprecated.py b/tests/plugins/loading/plugins/sources/deprecated/deprecated.py
new file mode 100644
index 000000000..6203eb2fa
--- /dev/null
+++ b/tests/plugins/loading/plugins/sources/deprecated/deprecated.py
@@ -0,0 +1,34 @@
+from buildstream import Source
+
+
+class Deprecated(Source):
+    BST_MIN_VERSION = "2.0"
+    BST_PLUGIN_DEPRECATED = True
+    BST_PLUGIN_DEPRECATION_MESSAGE = "Here is some detail."
+
+    def configure(self, node):
+        pass
+
+    def preflight(self):
+        pass
+
+    def get_unique_key(self):
+        return {}
+
+    def load_ref(self, node):
+        pass
+
+    def get_ref(self):
+        return {}
+
+    def set_ref(self, ref, node):
+        pass
+
+    def is_cached(self):
+        return False
+
+
+# Plugin entry point
+def setup():
+
+    return Deprecated