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

[Jessica Clarke]

On 22 May 2023, at 22:34, Conor Dooley <conor@xxxxxxxxxx> 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?

Jess