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

Signed-off-by: Jason Cooper <jason@lakedaemon.net>
---
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

Grant,

On Tue, Dec 17, 2013 at 04:59:40PM +0000, Jason Cooper wrote:
> Signed-off-by: Jason Cooper <jason@lakedaemon.net>
> ---
> 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

Are there any updates I should make to this?

thx,

Jason.

> 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@vger.kernel.org
> +
> +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@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Hi Jason,

Overall these are very nice and useful documents, but I have some minor
comments inline.

On Tuesday 17 of December 2013 16:59:40 Jason Cooper wrote:
> Signed-off-by: Jason Cooper <jason@lakedaemon.net>
> ---
> 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."

I'm not sure if my memory isn't playing tricks on me, but I think more
than that has been said. I believe we have decided that, if really
necessary, bindings can be marked as unstable, but they need to become
stable after some period of time (3 months?), otherwise they are dropped.
Also, the marking is supposed to be done by explicitly stating in
documentation that such binding is unstable.

Also it might be a good idea to state (even if it's quite obvious) that
standard kernel release processes apply to bindings, so they become
really stable after release of first stable kernel where relevant
documentation is included. This means that the binding can be heavily
changed in -rc releases, if there is such need.

> +
> +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@vger.kernel.org
> +
> +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.

Even though the general rules of patch submission apply and pinging
maintainers is a part of them, it might be a good idea to do a last
minute ping as a warning for DT maintainers to give them one more day
to look at patches that they could have missed.

> +
> +  3) For a series going though multiple trees, the binding patch should be
> +     kept with the driver using the binding.

Also a note about trivial bindings might be added, because there is a lot
of such showing up constantly. With trivial I mean a compatible string
and a set of some generic properties, such as reg, interrupts, etc.,
without any special device-specific magic. I'm not sure if there is
a need to wait for DT maintainers to act, if subsystem maintainer can
identify such binding as trivial.

Best regards,
Tomasz

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

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

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@vger.kernel.org
> +
> +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@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html