From d4672f008280e970455667486698046580644307 Mon Sep 17 00:00:00 2001
From: Cristian Le <cristian.le@mpsd.mpg.de>
Date: Fri, 24 May 2024 19:29:55 +0200
Subject: [PATCH] Document new feature

Signed-off-by: Cristian Le <cristian.le@mpsd.mpg.de>
---
 docs/code/plugin-introduction.rst | 50 +++++++++++++++++++++++++++++++
 docs/releases.rst                 |  7 +++++
 2 files changed, 57 insertions(+)

diff --git a/docs/code/plugin-introduction.rst b/docs/code/plugin-introduction.rst
index ddf34e7c77..0cbc70d3ba 100644
--- a/docs/code/plugin-introduction.rst
+++ b/docs/code/plugin-introduction.rst
@@ -16,6 +16,11 @@ provided in the ``TMT_PLUGINS`` environment variable and from
    Consider adding a static type checker (e.g. ``mypy``) in your
    plugin's CI using the ``main`` branch of ``tmt``.
 
+.. versionadded:: 1.38
+   You can use ``tmt.resources`` entry point to inject resource
+   files to be used for tmt, e.g. schemas or templates. See
+   :ref:`additional-resources` for more details.
+
 
 Inheritance
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -62,3 +67,48 @@ features which cannot be covered by generic ssh implementation of
 the ``Guest`` class.
 
 __ https://github.com/teemtee/tmt/tree/main/examples/plugins
+
+.. additional-resources:
+
+Additional resource files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to make resource files available to the base ``tmt``
+execution, you need to point a ``tmt.resources`` entry point to the
+root python package where the resource files are located from, e.g.
+with in the ``examples/plugins``:
+
+.. code-block:: toml
+   :caption: pyproject.toml
+   :emphasize-lines: 5,6
+
+   [project.entry-points."tmt.plugin"]
+   ProvisionExample = "example.provision:ProvisionExample"
+   DiscoverExample = "example.discover:DiscoverExample"
+
+   [project.entry-points."tmt.resources"]
+   ResourcesExample = "example"
+
+you can, for example, add a json schema file for the plugins
+implemented above by including the schema files under a ``schemas``
+folder:
+
+.. code-block:: shell
+
+   $ tree ./example
+   ./example
+   ├── __init__.py
+   ├── discover.py
+   ├── provision.py
+   └── schemas
+       ├── discover
+       │   └── example.yaml
+       └── provision
+           └── example.yaml
+
+.. note::
+
+   Both the entry-point entries as well as any resource file
+   under the ``tmt.resources`` path **must** have unique names.
+   Consider namespacing all relevant entries with the name of the
+   project or an unambiguous derivative of it.
diff --git a/docs/releases.rst b/docs/releases.rst
index c270cb6e0b..9e34e33534 100644
--- a/docs/releases.rst
+++ b/docs/releases.rst
@@ -4,6 +4,13 @@
     Releases
 ======================
 
+tmt-1.38.0
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+External plugins can inject additional resources to be used by tmt using
+the ``tmt.resources`` entry-point, e.g. to extend the schema validation
+or tmt templates.
+
 tmt-1.37.0
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~