docs: dt: writing-bindings: Express better expectations of "specific"
authorKrzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Mon, 7 Jul 2025 09:50:21 +0000 (11:50 +0200)
committerRob Herring (Arm) <robh@kernel.org>
Tue, 8 Jul 2025 12:22:12 +0000 (07:22 -0500)
commitb57ce9630bab1a468643fd5fb34d42cb936f0cb0
tree77a6b52c93db7f884b3f2e58104c3777703d1c03
parent49ed6868c10e2a11bb44ea836ecf88ca4122f303
docs: dt: writing-bindings: Express better expectations of "specific"

Devicetree bindings are supposed to be specific in terms of compatibles
and other properties.  Short "specific" has many implications, so extend
the description to cover them:

1. Mention no family names and avoid generic SoC fallbacks in
   compatible.  The list grew, mixing DO's and DON'T's, so split it into
   multiple items.

2. No properties implied by the compatible.

3. Document desired lack of ABI impact and acceptable solution if such
   needs arises: clearly marking it in commit msg.

All above follows established Devicetree bindings maintainers review
practice, so no new rules in practice are introduced here.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
Link: https://lore.kernel.org/r/20250707095019.66792-5-krzysztof.kozlowski@linaro.org
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
Documentation/devicetree/bindings/writing-bindings.rst