new file mode 100644
@@ -0,0 +1,68 @@
+
+ Submitting devicetree (DT) binding patches
+
+I. For patch submitters
+
+ 0) Normal patch submission rules from Documentation/SubmittingPatches
+ applies.
+
+ 1) The Documentation/ portion of the patch should be a separate patch
+ and clearly labelled as such. For example:
+
+ [PATCH X/Y] dt: binding: mvebu mbus driver
+
+ This makes the binding portion easy to find among large patch series.
+
+ 2) Submit the entire series to the devicetree mailinglist at
+
+ devicetree@vger.kernel.org
+
+II. For sub-system 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) 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.
+
+ 3) For a series going though multiple trees, the binding patch should be
+ kept with the driver using the binding.
+
+III. General binding rules
+
+ 1) Maintainers, don't let perfect be the enemy of good. Don't hold up a
+ binding because it isn't perfect.
+
+ 2) Use specific compatible strings so that if we need to add a feature (DMA)
+ in the future, we can create a new compatible string. See IV.2.
+
+ 3) Ideally, all bindings receive sufficient review. In the real world, we
+ need to prioritize. Bindings for a specific block of IP aren't as
+ critical as a binding for a common subsystem, like PCI.
+
+ 4) Don't submit bindings for staging or unstable. That will be decided by
+ the devicetree maintainers *after* discussion on the mailinglist.
+
+IV. Notes
+
+ 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.
+
+ 2) Regarding stable bindings/ABI, we quote from the 2013 ARM mini-summit
+ summary document:
+
+ "That still leaves the question of, what does a stable binding look
+ like? Certainly a stable binding means that a newer kernel will not
+ break on an older device tree, but that doesn't mean the binding is
+ frozen for all time. Grant said there are ways to change bindings that
+ don't result in breakage. For instance, if a new property is added,
+ then default to the previous behaviour if it is missing. If a binding
+ truly needs an incompatible change, then change the compatible string
+ at the same time. The driver can bind against both the old and the
+ new. These guidelines aren't new, but they desperately need to be
+ documented."
+
Signed-off-by: Jason Cooper <jason@lakedaemon.net> --- Changes since V1: - clarified III.1. as speaking to maintainers - quoted Grant's ARM mini-summit document regarding DT as stable ABI (IV.2.) All, Since I've now had to answer this question a couple of times, I thought it might be worth trying to put it in a document. I don't like long documents, so this is pretty concise, and most likely wrong. Hence, RFC. :) I also dislike quoting people from my imperfect memory, much better to have an agreed upon document we can point people towards. thx, Jason. .../devicetree/bindings/submitting-patches.txt | 68 ++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 Documentation/devicetree/bindings/submitting-patches.txt