Re: [PATCH v2] Documentation/process: add soc maintainer handbook
From: Jonathan Corbet <corbet@lwn.net>
Date: 2023-05-30 13:02:45
Also in:
linux-devicetree, linux-doc, linux-riscv, lkml
Conor Dooley [off-list ref] 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@arndb.de> Signed-off-by: Conor Dooley <conor.dooley@microchip.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...
quoted hunk ↗ jump to hunk
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.rstdiff --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 _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel