[PATCH v2] test-manual: Add initial YP Compatible documentation

[PATCH v2] test-manual: Add initial YP Compatible documentation

[Michael Opdenacker]

From: Richard Purdie <richard.purdie@linuxfoundation.org>

This starts documenting the Yocto Project Compatible badging programme. This
adds an initial piece of documentation about it from which we can improve
as needed.

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reviewed-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
---
 documentation/test-manual/index.rst           |   1 +
 .../test-manual/yocto-project-compatible.rst  | 124 ++++++++++++++++++
 2 files changed, 125 insertions(+)
 create mode 100644 documentation/test-manual/yocto-project-compatible.rst

diff --git a/documentation/test-manual/index.rst b/documentation/test-manual/index.rst
index d122b5e270..4c590a6aa9 100644
--- a/documentation/test-manual/index.rst
+++ b/documentation/test-manual/index.rst
@@ -14,6 +14,7 @@ Yocto Project Test Environment Manual
    test-process
    understand-autobuilder
    reproducible-builds
+   yocto-project-compatible
    history
 
 .. include:: /boilerplate.rst
diff --git a/documentation/test-manual/yocto-project-compatible.rst b/documentation/test-manual/yocto-project-compatible.rst
new file mode 100644
index 0000000000..a7897469ff
--- /dev/null
+++ b/documentation/test-manual/yocto-project-compatible.rst
@@ -0,0 +1,124 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+************************
+Yocto Project Compatible
+************************
+
+============
+Introduction
+============
+
+After the introduction of layers to OpenEmbedded, it quickly became clear
+that while some layers were popular and worked well, others developed a
+reputation for being "problematic". Those were layers which didn't
+interoperate well with others and tended to assume they controlled all
+the aspects of the final output.  This usually isn't intentional but happens
+because such layers are often created by developers with a particular focus
+(e.g. a company's :term:`BSP<Board Support Package (BSP)>`) whilst the end
+users have a different one (e.g. integrating that
+:term:`BSP<Board Support Package (BSP)>` into a product).
+
+As a result of noticing such patterns and friction between layers, the project
+developed the "Yocto Project Compatible" badge program, allowing layers
+following the best known practises to be marked as being widely compatible
+with other ones. This takes the form of a set of "yes/no" binary answer
+questions where layers can declare if they meet the appropriate criteria.
+In the second version of the program, a script was added to make validation
+easier and clearer, the script is called  ``yocto-check-layer`` and is
+available in :term:`OpenEmbedded-Core (OE-Core)`.
+
+See :ref:`dev-manual/common-tasks:making sure your layer is compatible with yocto project`
+for details.
+
+========
+Benefits
+========
+
+:ref:`overview-manual/yp-intro:the yocto project layer model` is powerful
+and flexible: it gives users the ultimate power to change pretty much any
+aspect of the system but as with most things, power comes with responsibility.
+The Yocto Project would like to see people able to mix and match BSPs with
+distro configs or software stacks and be able to merge succesfully.
+Over time, the project identified characteristics in layers that allow them
+to operate well together. "anti-patterns" were also found, preventing layers
+from working well together.
+
+The intent of the compatibility program is simple: if the layer passes the
+compatibility tests, it is considered "well behaved" and should operate
+and cooperate well with other compatible layers.
+
+The benefits of compatibility can be seen from multiple different user and
+member perspectives. From a hardware perspective
+(a :ref:`overview-manual/concepts:bsp layer`), compatibility means the
+hardware can be used in many different products and use cases without
+impacting the software stacks being run with it. For a company developing
+a product, compatibility gives you a specification / standard you can
+require in a contract and then know it will have certain desired
+characteristics for interoperability. It also puts constraints on how invasive
+the code bases are into the rest of the system, meaning that multiple
+different separate hardware support layers can coexist (e.g. for multiple
+product lines from different hardware manufacturers). This can also make it
+easier for one or more parties to upgrade those system components for security
+purposes during the lifecycle of a product.
+
+==================
+Validating a layer
+==================
+
+The badges are available to members of the Yocto Project (as member benefit)
+and to open source projects run on a non-commercial basis. However, anyone can
+answer the questions and run the script.
+
+The project encourages all layer maintainers to review the questions and the
+output from the script against their layer, as the way some layers are
+constructed often has unintended consequences. The questions and the script
+are designed to highlight known issues which are often easy to solve. This
+makes layers easier to use and therefore more popular.
+
+It is intended that over time, the tests will evolve as new best known
+practices are identified, and as new interoperability issues are found,
+unnecessarily restricting layer interoperability. If anyone becomes aware of
+either type, please let the project know through the
+:yocto_home:`technical calls </public-virtual-meetings/>`,
+the :yocto_home:`mailing lists </community/mailing-lists/>`
+or through the :oe_wiki:`Technical Steering Committee (TSC) </TSC>`.
+The TSC is responsible for the technical criteria used by the program.
+
+Layers are divided into three types:
+
+-  :ref:`"BSP" or "hardware support"<overview-manual/concepts:bsp layer>`
+   layers contain support for particular pieces of hardware. This includes
+   kernel and boot loader configuration, and any recipes for firmware or
+   kernel modules needed for the hardware. Such layers usually correspond
+   to a :term:`MACHINE` setting.
+
+-  :ref:`"distro" layers<overview-manual/concepts:distro layer>` defined
+   as layers providing configuration options and settings such as the
+   choice of init system, compiler and optimisation options, and
+   configuration and choices of software components. This would usually
+   correspond to a :term:`DISTRO` setting.
+
+-  "software" layers are usually recipes. A layer might target a
+   particular graphical UI or software stack component.
+
+Here are key best practices the program tries to encourage:
+
+-  A layer should clearly show who maintains it, and who change
+   submissions and bug reports should be sent to.
+
+-  Where multiple types of functionality are present, the layer should
+   be internally divided into sublayers to separate these components.
+   That's because some users may only need one of them and separability
+   is a key best practice.
+
+-  Adding a layer to a build should not modify that build, unless the
+   user changes a configuration setting to activate the layer, by selecting
+   a :term:`MACHINE`, a :term:`DISTRO` or a :term:`DISTRO_FEATURES` setting.
+
+The project does test the compatibility status of the core project layers on
+its :doc:`Autobuilder </test-manual/understand-autobuilder>`.
+
+The official form to submit compatibility requests with is at
+:yocto_home:`/ecosystem/branding/compatible-registration/`.
+Applicants can display the badge they get when their application is successful.
+
-- 
2.25.1