[PATCH] docs: dt: submitting-patches: Avoid 'schema' in subject and add an example

[PATCH] docs: dt: submitting-patches: Avoid 'schema' in subject and add an example

[Krzysztof Kozlowski]

Subjects should avoid also 'schema' keyword, because all bindings are
supposed to be in DT schema format.  Effectively people get confused
that subject should not contain anything else than device name after the
prefix, so add a recommended example.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
---
 Documentation/devicetree/bindings/submitting-patches.rst | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
index f3e23e69a638..bf32b784cb82 100644
--- a/Documentation/devicetree/bindings/submitting-patches.rst
+++ b/Documentation/devicetree/bindings/submitting-patches.rst
@@ -21,8 +21,12 @@ 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 "schema" 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"
 
   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

Re: [PATCH] docs: dt: submitting-patches: Avoid 'schema' in subject and add an example

[Rob Herring]

On Thu, Jul 10, 2025 at 10:58:15AM +0200, Krzysztof Kozlowski wrote:
> Subjects should avoid also 'schema' keyword, because all bindings are
> supposed to be in DT schema format.  Effectively people get confused
> that subject should not contain anything else than device name after the
> prefix, so add a recommended example.

However, conversions should because if you say don't say schema, then 
people will say YAML which I don't prefer. I prefer "convert foo to DT 
schema" as lots of things are YAML and only 1 thing is "DT schema".

> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> ---
>  Documentation/devicetree/bindings/submitting-patches.rst | 8 ++++++--
>  1 file changed, 6 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
> index f3e23e69a638..bf32b784cb82 100644
> --- a/Documentation/devicetree/bindings/submitting-patches.rst
> +++ b/Documentation/devicetree/bindings/submitting-patches.rst
> @@ -21,8 +21,12 @@ 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 "schema" 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"
>  
>    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
> 

Re: [PATCH] docs: dt: submitting-patches: Avoid 'schema' in subject and add an example

[Krzysztof Kozlowski]

On 11/07/2025 00:44, Rob Herring wrote:
> On Thu, Jul 10, 2025 at 10:58:15AM +0200, Krzysztof Kozlowski wrote:
>> Subjects should avoid also 'schema' keyword, because all bindings are
>> supposed to be in DT schema format.  Effectively people get confused
>> that subject should not contain anything else than device name after the
>> prefix, so add a recommended example.
> 
> However, conversions should because if you say don't say schema, then 
> people will say YAML which I don't prefer. I prefer "convert foo to DT 
> schema" as lots of things are YAML and only 1 thing is "DT schema".
OK, I can rephrase the commit msg and contents. Will be longer text, though.

Best regards,
Krzysztof