[PATCH 1/2] bitbake-setup: clarify configuration merging

From: Ernest Van Hoecke <[email protected]>

When nested configurations are used and the same key is present in both
configs being merged, the Python "+" behaviour is used. This leads to
lists being appended and strings being concatenated. The first is an
intuitive behaviour when specifying a tree of configs, the latter might
not be.

Clarify the configuration merging behaviour explicitly in the docs.

Signed-off-by: Ernest Van Hoecke <[email protected]>
---
 doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
index 77fc4c3dcba0..1252f22c823a 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
@@ -1068,6 +1068,12 @@ They contain the following sections:
       configuration choices by putting together information from a leaf
       configuration and all of its ancestors.
 
+      When the same keyword is present in a nested configuration and in one of
+      its ancestors, the values are merged with Python ``+`` semantics. For
+      example, lists are appended and strings are concatenated directly. String
+      values such as ``description`` should include any needed separators in
+      the configuration data.
+
    -  ``bb-env-passthrough-additions`` (*optional*): List of environment
       variables to include in :term:`BB_ENV_PASSTHROUGH_ADDITIONS`.
 

-- 
2.43.0