linux-kernel - Re: [PATCH v2] Documentation/process: add soc maintainer handbook

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87bki23rbx.fsf@meer.lwn.net>
Date:   Tue, 30 May 2023 07:02:26 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Conor Dooley <conor.dooley@...rochip.com>, soc@...nel.org
Cc:     conor@...nel.org, conor.dooley@...rochip.com,
        devicetree@...r.kernel.org, krzysztof.kozlowski+dt@...aro.org,
        linux-arm-kernel@...ts.infradead.org, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, linux-riscv@...ts.infradead.org,
        olof@...om.net, palmer@...belt.com, robh+dt@...nel.org,
        arnd@...db.de
Subject: Re: [PATCH v2] Documentation/process: add soc maintainer handbook

Conor Dooley <conor.dooley@...rochip.com> writes:

> Arnd suggested that adding a maintainer handbook for the SoC "subsystem"
> would be helpful in trying to bring on board maintainers for the various
> new platforms cropping up in RISC-V land.
>
> Add a document briefly describing the role of the SoC subsystem and some
> basic advice for (new) platform maintainers.
>
> Suggested-by: Arnd Bergmann <arnd@...db.de>
> Signed-off-by: Conor Dooley <conor.dooley@...rochip.com>
> ---
> Changes in v2:
> - add Krzysztof's suggested method for avoiding inter-branch
>   dependencies
> - explicitly mention that tags should be signed
> - link to the devicetree abi document, rather than trying to explain it
>   here & reword that whole section
> - fix some typos, capitalisation & unify bullet style
>
> The devicetree abi doc feels quite out of date at this point, and could
> probably do with a spring clean - but it also feels like hallowed ground
> on which one should tread lightly, so I won't go near that til Rob is
> back.

So, this is a nit, but worth considering...

>  Documentation/devicetree/bindings/ABI.rst     |   2 +
>  .../devicetree/bindings/writing-schema.rst    |   2 +
>  .../process/maintainer-handbooks.rst          |   3 +-
>  Documentation/process/maintainer-soc.rst      | 178 ++++++++++++++++++
>  MAINTAINERS                                   |   1 +
>  5 files changed, 185 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/process/maintainer-soc.rst
>
> diff --git a/Documentation/devicetree/bindings/ABI.rst b/Documentation/devicetree/bindings/ABI.rst
> index a885713cf184..93ec82f78ae5 100644
> --- a/Documentation/devicetree/bindings/ABI.rst
> +++ b/Documentation/devicetree/bindings/ABI.rst
> @@ -1,5 +1,7 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> +.. _devicetree-abi:

Somehow we've developed this habit of putting labels at the top of each
file; I really think that they just add clutter and are best left out.
Without the label, this reference:

> +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` more information on the ABI.

...can just be written as "Please see
Documentation/devicetree/bindings/ABI.rst".  The cross-reference link
will be generated as expected, and readers of the plain-text docs don't
have to go grepping to find the reference.

Thanks,

jon