From: Mauro Carvalho Chehab Date: Wed, 15 Apr 2020 14:45:25 +0000 (+0200) Subject: docs: dt: convert submitting-patches.txt to ReST format X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=858e6845654d;p=linux.git docs: dt: convert submitting-patches.txt to ReST format - Add a SPDX header; - Adjust document and section titles; - Mark literal blocks as such; - Add it to bindings/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Rob Herring --- diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst index 98ebdab24b516..6b87875a049c9 100644 --- a/Documentation/devicetree/bindings/index.rst +++ b/Documentation/devicetree/bindings/index.rst @@ -8,3 +8,4 @@ Device Tree :maxdepth: 1 ABI + submitting-patches diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst new file mode 100644 index 0000000000000..0aab2b3f16d02 --- /dev/null +++ b/Documentation/devicetree/bindings/submitting-patches.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================== +Submitting devicetree (DT) binding patches +========================================== + +I. For patch submitters +======================= + + 0) Normal patch submission rules from Documentation/process/submitting-patches.rst + applies. + + 1) The Documentation/ and include/dt-bindings/ portion of the patch should + be a separate patch. The preferred subject prefix for binding patches is:: + + "dt-bindings: : ..." + + The 80 characters of the subject are precious. It is recommended to not + use "Documentation" or "doc" because that is implied. All bindings are + docs. Repeating "binding" again should also be avoided. + + 2) DT binding files are written in DT schema format using json-schema + vocabulary and YAML file format. The DT binding files must pass validation + by running:: + + make dt_binding_check + + See ../writing-schema.rst for more details about schema and tools setup. + + 3) DT binding files should be dual licensed. The preferred license tag is + (GPL-2.0-only OR BSD-2-Clause). + + 4) Submit the entire series to the devicetree mailinglist at + + devicetree@vger.kernel.org + + and Cc: the DT maintainers. Use scripts/get_maintainer.pl to identify + all of the DT maintainers. + + 5) The Documentation/ portion of the patch should come in the series before + the code implementing the binding. + + 6) Any compatible strings used in a chip or board DTS file must be + previously documented in the corresponding DT binding text file + in Documentation/devicetree/bindings. This rule applies even if + the Linux device driver does not yet match on the compatible + string. [ checkpatch will emit warnings if this step is not + followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864 + ("checkpatch: add DT compatible string documentation checks"). ] + + 7) The wildcard "" may be used in compatible strings, as in + the following example: + + - compatible: Must contain '"nvidia,-pcie", + "nvidia,tegra20-pcie"' where is tegra30, tegra132, ... + + As in the above example, the known values of "" should be + documented if it is used. + + 8) If a documented compatible string is not yet matched by the + driver, the documentation should also include a compatible + string that is matched by the driver (as in the "nvidia,tegra20-pcie" + example above). + + +II. For kernel maintainers +========================== + + 1) If you aren't comfortable reviewing a given binding, reply to it and ask + the devicetree maintainers for guidance. This will help them prioritize + which ones to review and which ones are ok to let go. + + 2) For driver (not subsystem) bindings: If you are comfortable with the + binding, and it hasn't received an Acked-by from the devicetree + maintainers after a few weeks, go ahead and take it. + + Subsystem bindings (anything affecting more than a single device) + then getting a devicetree maintainer to review it is required. + + 3) For a series going though multiple trees, the binding patch should be + kept with the driver using the binding. + +III. Notes +========== + + 0) Please see ...bindings/ABI.txt for details regarding devicetree ABI. + + 1) This document is intended as a general familiarization with the process as + decided at the 2013 Kernel Summit. When in doubt, the current word of the + devicetree maintainers overrules this document. In that situation, a patch + updating this document would be appreciated. diff --git a/Documentation/devicetree/bindings/submitting-patches.txt b/Documentation/devicetree/bindings/submitting-patches.txt deleted file mode 100644 index 98bee6240b65f..0000000000000 --- a/Documentation/devicetree/bindings/submitting-patches.txt +++ /dev/null @@ -1,85 +0,0 @@ - - Submitting devicetree (DT) binding patches - -I. For patch submitters - - 0) Normal patch submission rules from Documentation/process/submitting-patches.rst - applies. - - 1) The Documentation/ and include/dt-bindings/ portion of the patch should - be a separate patch. The preferred subject prefix for binding patches is: - - "dt-bindings: : ..." - - The 80 characters of the subject are precious. It is recommended to not - use "Documentation" or "doc" because that is implied. All bindings are - docs. Repeating "binding" again should also be avoided. - - 2) DT binding files are written in DT schema format using json-schema - vocabulary and YAML file format. The DT binding files must pass validation - by running: - - make dt_binding_check - - See ../writing-schema.rst for more details about schema and tools setup. - - 3) DT binding files should be dual licensed. The preferred license tag is - (GPL-2.0-only OR BSD-2-Clause). - - 4) Submit the entire series to the devicetree mailinglist at - - devicetree@vger.kernel.org - - and Cc: the DT maintainers. Use scripts/get_maintainer.pl to identify - all of the DT maintainers. - - 5) The Documentation/ portion of the patch should come in the series before - the code implementing the binding. - - 6) Any compatible strings used in a chip or board DTS file must be - previously documented in the corresponding DT binding text file - in Documentation/devicetree/bindings. This rule applies even if - the Linux device driver does not yet match on the compatible - string. [ checkpatch will emit warnings if this step is not - followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864 - ("checkpatch: add DT compatible string documentation checks"). ] - - 7) The wildcard "" may be used in compatible strings, as in - the following example: - - - compatible: Must contain '"nvidia,-pcie", - "nvidia,tegra20-pcie"' where is tegra30, tegra132, ... - - As in the above example, the known values of "" should be - documented if it is used. - - 8) If a documented compatible string is not yet matched by the - driver, the documentation should also include a compatible - string that is matched by the driver (as in the "nvidia,tegra20-pcie" - example above). - - -II. For kernel maintainers - - 1) If you aren't comfortable reviewing a given binding, reply to it and ask - the devicetree maintainers for guidance. This will help them prioritize - which ones to review and which ones are ok to let go. - - 2) For driver (not subsystem) bindings: If you are comfortable with the - binding, and it hasn't received an Acked-by from the devicetree - maintainers after a few weeks, go ahead and take it. - - Subsystem bindings (anything affecting more than a single device) - then getting a devicetree maintainer to review it is required. - - 3) For a series going though multiple trees, the binding patch should be - kept with the driver using the binding. - -III. Notes - - 0) Please see ...bindings/ABI.txt for details regarding devicetree ABI. - - 1) This document is intended as a general familiarization with the process as - decided at the 2013 Kernel Summit. When in doubt, the current word of the - devicetree maintainers overrules this document. In that situation, a patch - updating this document would be appreciated. diff --git a/Documentation/devicetree/bindings/writing-bindings.txt b/Documentation/devicetree/bindings/writing-bindings.txt index 27dfd2d8016e2..ca024b9c7433b 100644 --- a/Documentation/devicetree/bindings/writing-bindings.txt +++ b/Documentation/devicetree/bindings/writing-bindings.txt @@ -4,7 +4,7 @@ This is a list of common review feedback items focused on binding design. With every rule, there are exceptions and bindings have many gray areas. For guidelines related to patches, see -Documentation/devicetree/bindings/submitting-patches.txt +Documentation/devicetree/bindings/submitting-patches.rst Overall design diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index ba5e944c7a63a..1699b7f8e63ab 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -16,7 +16,7 @@ for a list of items to check before submitting code. If you are submitting a driver, also read :ref:`Documentation/process/submitting-drivers.rst `; for device tree binding patches, read -Documentation/devicetree/bindings/submitting-patches.txt. +Documentation/devicetree/bindings/submitting-patches.rst. Many of these steps describe the default behavior of the ``git`` version control system; if you use ``git`` to prepare your patches, you'll find much diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index cba1f8cb61ed1..7c23c08e44018 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -21,7 +21,7 @@ Leggete anche :ref:`Documentation/translations/it_IT/process/submit-checklist.rs per una lista di punti da verificare prima di inviare del codice. Se state inviando un driver, allora leggete anche :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst `; per delle patch relative alle associazioni per Device Tree leggete -Documentation/devicetree/bindings/submitting-patches.txt. +Documentation/devicetree/bindings/submitting-patches.rst. Molti di questi passi descrivono il comportamento di base del sistema di controllo di versione ``git``; se utilizzate ``git`` per preparare le vostre diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index d64c67b67e3c7..7d237a4598aea 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -2594,7 +2594,7 @@ sub process { if (($last_binding_patch != -1) && ($last_binding_patch ^ $is_binding_patch)) { WARN("DT_SPLIT_BINDING_PATCH", - "DT binding docs and includes should be a separate patch. See: Documentation/devicetree/bindings/submitting-patches.txt\n"); + "DT binding docs and includes should be a separate patch. See: Documentation/devicetree/bindings/submitting-patches.rst\n"); } }