[PATCH v1] Documentation/process: add soc maintainer handbook

[Conor Dooley]

On 23 May 2023 01:32:49 IST, Jessica Clarke <jrtc27 at jrtc27.com> wrote:
>On 22 May 2023, at 22:34, Conor Dooley <conor at kernel.org> wrote:
>> 
>> On Tue, May 16, 2023 at 10:31:19AM +0200, Krzysztof Kozlowski wrote:
>>> On 15/05/2023 21:20, Conor Dooley wrote:
>> 
>>>> +devicetree ABI stability
>>>> +~~~~~~~~~~~~~~~~~~~~~~~~
>>>> +
>>>> +Perhaps one of the most important things to highlight is that dt-bindings
>>>> +document the ABI between the devicetree and the kernel.  Once dt-bindings have
>>>> +been merged (and appear in a release of the kernel) they are set in stone, and
>>>> +any changes made must be compatible with existing devicetrees.  This means that,
>>>> +when changing properties, a "new" kernel must still be able to handle an old
>>>> +devicetree.  For many systems the devicetree is provided by firmware, and
>>>> +upgrading to a newer kernel cannot cause regressions.  Ideally, the inverse is
>>>> +also true, and a new devicetree will also be compatible with an old kernel,
>>>> +although this is often not possible.
>>> 
>>> I would prefer to skip it and instead: enhance
>>> Documentation/devicetree/bindings/ABI.rst and then reference it here.
>>> 
>>>> +
>>>> +If changes are being made to a devicetree that are incompatible with old
>>>> +kernels, the devicetree patch should not be applied until the driver is, or an
>>>> +appropriate time later.  Most importantly, any incompatible changes should be
>>>> +clearly pointed out in the patch description and pull request, along with the
>>>> +expected impact on existing users.
>> 
>> I'm not really sure that I like this truncated section so much, but here
>> it is... I kept the last paragraph intact as it does not talk about the
>> ABI, but rather exceptions of submaintainers.
>> 
>> devicetree ABI stability
>> ~~~~~~~~~~~~~~~~~~~~~~~~
>> 
>> Perhaps one of the most important things to highlight is that dt-bindings
>> document the ABI between the devicetree and the kernel. Please see
>> :ref:`devicetree-abi` for devicetree ABI rules.
>> 
>> If changes are being made to a devicetree that are incompatible with old
>> kernels, the devicetree patch should not be applied until the driver is, or an
>> appropriate time later.  Most importantly, any incompatible changes should be
>> clearly pointed out in the patch description and pull request, along with the
>> expected impact on existing users.
>
>Do you have an opinion on acknowledging the existence of other OSes here?

I think that is fair.