From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
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 <mchehab+huawei@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
---
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: <binding dir>: ..."
+
+ 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 "<chip>" may be used in compatible strings, as in
+ the following example:
+
+ - compatible: Must contain '"nvidia,<chip>-pcie",
+ "nvidia,tegra20-pcie"' where <chip> is tegra30, tegra132, ...
+
+ As in the above example, the known values of "<chip>" 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: <binding dir>: ..."
-
- 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 "<chip>" may be used in compatible strings, as in
- the following example:
-
- - compatible: Must contain '"nvidia,<chip>-pcie",
- "nvidia,tegra20-pcie"' where <chip> is tegra30, tegra132, ...
-
- As in the above example, the known values of "<chip>" 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 <submittingdrivers>`;
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 <it_submittingdrivers>`;
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");
}
}