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

[Conor Dooley]

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.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: not available
URL: <http://lists.infradead.org/pipermail/linux-riscv/attachments/20230522/089abad3/attachment.sig>