Re: [PATCH V2] dt: bindings: submitting patches and ABI documents

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 




On Tue, 17 Dec 2013 16:59:40 +0000, Jason Cooper <jason@xxxxxxxxxxxxxx> wrote:
> Signed-off-by: Jason Cooper <jason@xxxxxxxxxxxxxx>

Applied, thanks.

One note though. Even when the diff is "obvious", the commit description
should really not be empty. I've added something, but my life is a lot
easier when I don't have to.

I've also added the following blurb to point II.2:

+     Subsystem bindings (anything affecting more than a single device)
+     then getting a devicetree maintainer to review it is required.

g.

> ---
> Changes from RFC:
>  - incorporated Grant's language
>  - split patches/ABI into two documents
> 
>  Documentation/devicetree/bindings/ABI.txt          | 39 ++++++++++++++++++++++
>  .../devicetree/bindings/submitting-patches.txt     | 35 +++++++++++++++++++
>  2 files changed, 74 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/ABI.txt
>  create mode 100644 Documentation/devicetree/bindings/submitting-patches.txt
> 
> diff --git a/Documentation/devicetree/bindings/ABI.txt b/Documentation/devicetree/bindings/ABI.txt
> new file mode 100644
> index 000000000000..d25f8d379680
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/ABI.txt
> @@ -0,0 +1,39 @@
> +
> +  Devicetree (DT) ABI
> +
> +I. 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."
> +
> +II.  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 I.
> +
> +  3) Bindings can be augmented, but the driver shouldn't break when given
> +     the old binding. ie. add additional properties, but don't change the
> +     meaning of an existing property. For drivers, default to the original
> +     behaviour when a newly added property is missing.
> +
> +  4) Don't submit bindings for staging or unstable.  That will be decided by
> +     the devicetree maintainers *after* discussion on the mailinglist.
> +
> +III. 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.
> diff --git a/Documentation/devicetree/bindings/submitting-patches.txt b/Documentation/devicetree/bindings/submitting-patches.txt
> new file mode 100644
> index 000000000000..5672cb46681d
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/submitting-patches.txt
> @@ -0,0 +1,35 @@
> +
> +  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.
> +
> +  2) Submit the entire series to the devicetree mailinglist at
> +
> +       devicetree@xxxxxxxxxxxxxxx
> +
> +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.
> +
> +  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.
> -- 
> 1.8.5.1
> 

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html




[Index of Archives]     [Device Tree Compilter]     [Device Tree Spec]     [Linux Driver Backports]     [Video for Linux]     [Linux USB Devel]     [Linux PCI Devel]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Yosemite Backpacking]
  Powered by Linux