Patches adding new device bindings should avoid 'YAML' keyword in the
subject, because all bindings are supposed to be in DT schema format,
which uses YAML.  The DT schema is welcomed only in case of patches
doing conversion.  Effectively people get confused that subject should
not contain anything else than device name after the prefix, so add two
recommended examples.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

---

Changes in v2:
1. Rephrase - use YAML instead of schema, add another example for
   conversion.
---
 Documentation/devicetree/bindings/submitting-patches.rst | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
index f3e23e69a6389e7e5d8db66af5060978ecff8a9d..46d0b036c97eb531dec95ef52261988d3bfa3aad 100644
--- a/Documentation/devicetree/bindings/submitting-patches.rst
+++ b/Documentation/devicetree/bindings/submitting-patches.rst
@@ -21,8 +21,16 @@ I. For patch submitters
        "<binding dir>: dt-bindings: ..."
 
      The 80 characters of the subject are precious. It is recommended to not
-     use "Documentation" or "doc" because that is implied. All bindings are
-     docs. Repeating "binding" again should also be avoided.
+     use "Documentation", "doc" or "YAML" because that is implied. All
+     bindings are docs and all new bindings are supposed to be in Devicetree
+     schema format.  Repeating "binding" again should also be avoided, so for
+     a new device it is often enough for example::
+
+       "dt-bindings: iio: adc: Add ROHM BD79100G"
+
+     Conversion of other formats to DT schema::
+
+       "dt-bindings: iio: adc: adi,ad7476: Convert to DT schema"
 
   2) DT binding files are written in DT schema format using json-schema
      vocabulary and YAML file format. The DT binding files must pass validation

-- 
2.43.0

On Sun, 13 Jul 2025 14:46:36 +0200, Krzysztof Kozlowski wrote:
> Patches adding new device bindings should avoid 'YAML' keyword in the
> subject, because all bindings are supposed to be in DT schema format,
> which uses YAML.  The DT schema is welcomed only in case of patches
> doing conversion.  Effectively people get confused that subject should
> not contain anything else than device name after the prefix, so add two
> recommended examples.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> 
> ---
> 
> Changes in v2:
> 1. Rephrase - use YAML instead of schema, add another example for
>    conversion.
> ---
>  Documentation/devicetree/bindings/submitting-patches.rst | 12 ++++++++++--
>  1 file changed, 10 insertions(+), 2 deletions(-)
> 

Applied, thanks!

On Sun, Jul 13, 2025 at 02:46:36PM +0200, Krzysztof Kozlowski wrote:
> Patches adding new device bindings should avoid 'YAML' keyword in the
> subject, because all bindings are supposed to be in DT schema format,
> which uses YAML.  The DT schema is welcomed only in case of patches
> doing conversion.  Effectively people get confused that subject should
> not contain anything else than device name after the prefix, so add two
> recommended examples.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> 
> ---
> 
> Changes in v2:
> 1. Rephrase - use YAML instead of schema, add another example for
>    conversion.
> ---
>  Documentation/devicetree/bindings/submitting-patches.rst | 12 ++++++++++--
>  1 file changed, 10 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
> index f3e23e69a6389e7e5d8db66af5060978ecff8a9d..46d0b036c97eb531dec95ef52261988d3bfa3aad 100644
> --- a/Documentation/devicetree/bindings/submitting-patches.rst
> +++ b/Documentation/devicetree/bindings/submitting-patches.rst
> @@ -21,8 +21,16 @@ I. For patch submitters
>         "<binding dir>: dt-bindings: ..."
>  
>       The 80 characters of the subject are precious. It is recommended to not
> -     use "Documentation" or "doc" because that is implied. All bindings are
> -     docs. Repeating "binding" again should also be avoided.
> +     use "Documentation", "doc" or "YAML" because that is implied. All
                                                                     ^
> +     bindings are docs and all new bindings are supposed to be in Devicetree
> +     schema format.  Repeating "binding" again should also be avoided, so for
                      ^^
I like the change, but I would like to note that you've got inconsistent
double space v single space after a full stop. The document seems to
mostly be confused about that and uses both. No clue which of the two it
should be, just wanted to mention it :)

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>


> +     a new device it is often enough for example::
> +
> +       "dt-bindings: iio: adc: Add ROHM BD79100G"
> +
> +     Conversion of other formats to DT schema::
> +
> +       "dt-bindings: iio: adc: adi,ad7476: Convert to DT schema"
>  
>    2) DT binding files are written in DT schema format using json-schema
>       vocabulary and YAML file format. The DT binding files must pass validation
> 
> -- 
> 2.43.0
>