diff mbox series

[v2,2/3] Documentation/process: maintainer-soc: add clean platforms profile

Message ID 20230719143309.204766-2-krzysztof.kozlowski@linaro.org (mailing list archive)
State Superseded
Headers show
Series [v2,1/3] MAINTAINERS: soc: reference maintainer profile | expand

Commit Message

Krzysztof Kozlowski July 19, 2023, 2:33 p.m. UTC
Some SoC platforms require that commits must not bring any new
dtbs_check warnings.  Maintainers of such platforms usually have some
automation set, so any new warning will be spotted sooner or later.
Worst case: they run the tests themselves.  Document requirements for
such platforms, so contributors can expect their patches being dropped
or ignored, if they bring new warnings for existing boards.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

---

Changes in v2:
1. Add Rb tag.
2. Implement Conor's feedback: change doc title, follow->should follow,
   minor style changes.
---
 .../process/maintainer-handbooks.rst          |  1 +
 .../process/maintainer-soc-clean-dts.rst      | 23 +++++++++++++++++++
 MAINTAINERS                                   |  2 +-
 3 files changed, 25 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/process/maintainer-soc-clean-dts.rst

Comments

Rob Herring July 19, 2023, 5:40 p.m. UTC | #1
On Wed, Jul 19, 2023 at 8:33 AM Krzysztof Kozlowski
<krzysztof.kozlowski@linaro.org> wrote:
>
> Some SoC platforms require that commits must not bring any new
> dtbs_check warnings.  Maintainers of such platforms usually have some
> automation set, so any new warning will be spotted sooner or later.
> Worst case: they run the tests themselves.  Document requirements for
> such platforms, so contributors can expect their patches being dropped
> or ignored, if they bring new warnings for existing boards.
>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
>
> ---
>
> Changes in v2:
> 1. Add Rb tag.
> 2. Implement Conor's feedback: change doc title, follow->should follow,
>    minor style changes.
> ---
>  .../process/maintainer-handbooks.rst          |  1 +
>  .../process/maintainer-soc-clean-dts.rst      | 23 +++++++++++++++++++
>  MAINTAINERS                                   |  2 +-
>  3 files changed, 25 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/process/maintainer-soc-clean-dts.rst
>
> diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
> index 9992bfd7eaa3..976391cec528 100644
> --- a/Documentation/process/maintainer-handbooks.rst
> +++ b/Documentation/process/maintainer-handbooks.rst
> @@ -17,5 +17,6 @@ Contents:
>
>     maintainer-netdev
>     maintainer-soc
> +   maintainer-soc-clean-dts
>     maintainer-tip
>     maintainer-kvm-x86
> diff --git a/Documentation/process/maintainer-soc-clean-dts.rst b/Documentation/process/maintainer-soc-clean-dts.rst
> new file mode 100644
> index 000000000000..c460923f39be
> --- /dev/null
> +++ b/Documentation/process/maintainer-soc-clean-dts.rst
> @@ -0,0 +1,23 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==============================================
> +SoC Platforms with DTS Compliance Requirements
> +==============================================
> +
> +Overview
> +--------
> +
> +SoC platforms or subarchitectures should follow all the rules from
> +Documentation/process/maintainer-soc.rst.  However platforms referencing
> +this document impose additional requirements listed below.

I would make it clear how platforms reference this doc:
this document in MAINTAINERS impose...

> +
> +Strict DTS DT Schema Compliance

Schema and dtc


> +-------------------------------
> +
> +No changes to the SoC platform Devicetree sources (DTS files) should introduce
> +new ``make dtbs_check W=1`` warnings.  The platform maintainers have automation
> +in place which should point out any new warnings.

If a soc.dtsi file has warnings a new board.dts will duplicate all
those warnings. I imagine those are okay? Or are we assuming soc.dtsi
is warning free? Or do we need to distinguish both cases?

I would like to see a build target for the warning free platforms, so
we can easily run it and check for no warnings. Just hasn't been
enough platforms yet to do that.

> +
> +If a commit introducing new warning gets accepted somehow, the resulting issues
> +shall be fixed in reasonable time (e.g. within one release) or the commit
> +reverted.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index ba5e7344f30e..a70c32790427 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1573,7 +1573,7 @@ S:        Maintained
>  P:     Documentation/process/maintainer-soc.rst
>  C:     irc://irc.libera.chat/armlinux
>  T:     git git://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git
> -F:     Documentation/process/maintainer-soc.rst
> +F:     Documentation/process/maintainer-soc*.rst
>  F:     arch/arm/boot/dts/Makefile
>  F:     arch/arm64/boot/dts/Makefile
>
> --
> 2.34.1
>
Krzysztof Kozlowski July 19, 2023, 5:55 p.m. UTC | #2
On 19/07/2023 19:40, Rob Herring wrote:
> On Wed, Jul 19, 2023 at 8:33 AM Krzysztof Kozlowski
> <krzysztof.kozlowski@linaro.org> wrote:
>>
>> Some SoC platforms require that commits must not bring any new
>> dtbs_check warnings.  Maintainers of such platforms usually have some
>> automation set, so any new warning will be spotted sooner or later.
>> Worst case: they run the tests themselves.  Document requirements for
>> such platforms, so contributors can expect their patches being dropped
>> or ignored, if they bring new warnings for existing boards.
>>
>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
>> Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
>>
>> ---
>>
>> Changes in v2:
>> 1. Add Rb tag.
>> 2. Implement Conor's feedback: change doc title, follow->should follow,
>>    minor style changes.
>> ---
>>  .../process/maintainer-handbooks.rst          |  1 +
>>  .../process/maintainer-soc-clean-dts.rst      | 23 +++++++++++++++++++
>>  MAINTAINERS                                   |  2 +-
>>  3 files changed, 25 insertions(+), 1 deletion(-)
>>  create mode 100644 Documentation/process/maintainer-soc-clean-dts.rst
>>
>> diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
>> index 9992bfd7eaa3..976391cec528 100644
>> --- a/Documentation/process/maintainer-handbooks.rst
>> +++ b/Documentation/process/maintainer-handbooks.rst
>> @@ -17,5 +17,6 @@ Contents:
>>
>>     maintainer-netdev
>>     maintainer-soc
>> +   maintainer-soc-clean-dts
>>     maintainer-tip
>>     maintainer-kvm-x86
>> diff --git a/Documentation/process/maintainer-soc-clean-dts.rst b/Documentation/process/maintainer-soc-clean-dts.rst
>> new file mode 100644
>> index 000000000000..c460923f39be
>> --- /dev/null
>> +++ b/Documentation/process/maintainer-soc-clean-dts.rst
>> @@ -0,0 +1,23 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +==============================================
>> +SoC Platforms with DTS Compliance Requirements
>> +==============================================
>> +
>> +Overview
>> +--------
>> +
>> +SoC platforms or subarchitectures should follow all the rules from
>> +Documentation/process/maintainer-soc.rst.  However platforms referencing
>> +this document impose additional requirements listed below.
> 
> I would make it clear how platforms reference this doc:
> this document in MAINTAINERS impose...

Sure.

> 
>> +
>> +Strict DTS DT Schema Compliance
> 
> Schema and dtc
Ack

> 
> 
>> +-------------------------------
>> +
>> +No changes to the SoC platform Devicetree sources (DTS files) should introduce
>> +new ``make dtbs_check W=1`` warnings.  The platform maintainers have automation
>> +in place which should point out any new warnings.
> 
> If a soc.dtsi file has warnings a new board.dts will duplicate all
> those warnings. I imagine those are okay? 

This. I would assume that these were existing warnings, so new board
does not add anything new. Different question if new board comes with
the same warning for compatible in TXT (not DT schema).

> Or are we assuming soc.dtsi
> is warning free? Or do we need to distinguish both cases?

Warning free, or at least not many warnings, should be implied,
otherwise I don't think it is possible to spot new warnings.


> 
> I would like to see a build target for the warning free platforms, so
> we can easily run it and check for no warnings. Just hasn't been
> enough platforms yet to do that.
> 
Best regards,
Krzysztof
diff mbox series

Patch

diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 9992bfd7eaa3..976391cec528 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -17,5 +17,6 @@  Contents:
 
    maintainer-netdev
    maintainer-soc
+   maintainer-soc-clean-dts
    maintainer-tip
    maintainer-kvm-x86
diff --git a/Documentation/process/maintainer-soc-clean-dts.rst b/Documentation/process/maintainer-soc-clean-dts.rst
new file mode 100644
index 000000000000..c460923f39be
--- /dev/null
+++ b/Documentation/process/maintainer-soc-clean-dts.rst
@@ -0,0 +1,23 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================================
+SoC Platforms with DTS Compliance Requirements
+==============================================
+
+Overview
+--------
+
+SoC platforms or subarchitectures should follow all the rules from
+Documentation/process/maintainer-soc.rst.  However platforms referencing
+this document impose additional requirements listed below.
+
+Strict DTS DT Schema Compliance
+-------------------------------
+
+No changes to the SoC platform Devicetree sources (DTS files) should introduce
+new ``make dtbs_check W=1`` warnings.  The platform maintainers have automation
+in place which should point out any new warnings.
+
+If a commit introducing new warning gets accepted somehow, the resulting issues
+shall be fixed in reasonable time (e.g. within one release) or the commit
+reverted.
diff --git a/MAINTAINERS b/MAINTAINERS
index ba5e7344f30e..a70c32790427 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1573,7 +1573,7 @@  S:	Maintained
 P:	Documentation/process/maintainer-soc.rst
 C:	irc://irc.libera.chat/armlinux
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git
-F:	Documentation/process/maintainer-soc.rst
+F:	Documentation/process/maintainer-soc*.rst
 F:	arch/arm/boot/dts/Makefile
 F:	arch/arm64/boot/dts/Makefile