Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <66cff026-3e7d-f88b-e99f-8100233231bb@linaro.org>
Date:   Mon, 17 Jul 2023 09:58:00 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.13.0
Subject: Re: [PATCH 2/3] Documentation/process: maintainer-soc: add clean
 platforms profile
Content-Language: en-US
To:     Conor Dooley <conor@kernel.org>
Cc:     Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        Paul Walmsley <paul.walmsley@sifive.com>,
        Palmer Dabbelt <palmer@dabbelt.com>,
        Albert Ou <aou@eecs.berkeley.edu>,
        Alim Akhtar <alim.akhtar@samsung.com>,
        Andy Gross <agross@kernel.org>,
        Bjorn Andersson <andersson@kernel.org>,
        Konrad Dybcio <konrad.dybcio@linaro.org>,
        Nishanth Menon <nm@ti.com>, linux-riscv@lists.infradead.org,
        devicetree@vger.kernel.org, linux-kernel@vger.kernel.org,
        linux-arm-kernel@lists.infradead.org,
        linux-samsung-soc@vger.kernel.org, linux-arm-msm@vger.kernel.org,
        Jonathan Corbet <corbet@lwn.net>,
        Arnd Bergmann <arnd@arndb.de>, Olof Johansson <olof@lixom.net>,
        soc@kernel.org, workflows@vger.kernel.org,
        linux-doc@vger.kernel.org
References: <20230714084725.27847-1-krzysztof.kozlowski@linaro.org>
 <20230714084725.27847-2-krzysztof.kozlowski@linaro.org>
 <20230714-verbose-unwound-fb8b1df29d25@spud>
From:   Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
In-Reply-To: <20230714-verbose-unwound-fb8b1df29d25@spud>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 14/07/2023 14:50, Conor Dooley wrote:
> Hey Krzysztof,
> 
> On Fri, Jul 14, 2023 at 10:47:24AM +0200, Krzysztof Kozlowski 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.
> 
> Definitely a more scalable approach than your previous version!
> 
>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
>> ---
>>  .../process/maintainer-handbooks.rst          |  1 +
>>  .../process/maintainer-soc-clean-dts.rst      | 22 +++++++++++++++++++
>>  MAINTAINERS                                   |  2 +-
>>  3 files changed, 24 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..87feeb5543ff
>> --- /dev/null
>> +++ b/Documentation/process/maintainer-soc-clean-dts.rst
>> @@ -0,0 +1,22 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +=============================
>> +SoC Platforms with Strict DTS
> 
> I don't think that this title makes much sense, it feels like it has
> been truncated. Perhaps add "Requirements" to the end?

OK, but maybe better then

SoC Platforms with DTS Compliance Requirements
?

> 
>> +=============================
>> +
>> +Overview
>> +--------
>> +
>> +SoC platforms or subarchitectures follow all the rules from
> 
> s/follow/should follow/?

Ack

> 
>> +Documentation/process/maintainer-soc.rst.  However platforms referencing this
>> +document impose additional requirements listed below.
>> +
>> +Strict DTS DT schema compliance
>> +-------------------------------
> Should there be a blank line here to match the other section headings?

Ack

> Also, to match the title case you used elsewhere, "Schema Compliance"?

Ack

> 
>> +None of the changes to the SoC platform Devicetree sources (DTS files) can
>> +bring new ``make dtbs_check W=1`` warnings.  The platform maintainers have
> 
> Nitpickery again, but perhaps the first sentence here would read better as
> "No changes to the SoC platform Devicetree sources (DTS files) should
> introduce new ``make dtbs_check W=1`` warnings."?

Ack

> 
>> +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.
> 
> It is loosely related, but I was wondering if we should also try to push
> people that change the platform's bindings to update the DTS also, so
> that binding changes do not introduce W=1 complaints?

Makes sense, we could add such rule to Devicetree maintainer profile.
Anyway enforcing it relies on Rob's bot reporting the warnings, which
seems silent recently.

> For many bindings the platform entry in MAINTAINERS does not cover them,
> but things like the arm64 Apple stuff mention them specifically & others
> will get coverage due to regexes.
> 
> Anyway, nitpickery aside I like this approach.
> Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
> 


Best regards,
Krzysztof