2 files changed, 17 insertions, 23 deletions

diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
index 89c8466933..c649e2bd60 100644
--- a/documentation/dev-manual/layers.rst
+++ b/documentation/dev-manual/layers.rst
@@ -470,11 +470,23 @@ corresponding recipe file. For example, the append file
 means the original recipe and append filenames are version
 number-specific. If the corresponding recipe is renamed to update to a
 newer version, you must also rename and possibly update the
-corresponding ``.bbappend`` as well. During the build process, BitBake
-displays an error on starting if it detects a ``.bbappend`` file that
-does not have a corresponding recipe with a matching name. See the
-:term:`BB_DANGLINGAPPENDS_WARNONLY`
-variable for information on how to handle this error.
+corresponding ``.bbappend`` as well.
+
+During the build process, BitBake displays an error on startup if it detects a
+``.bbappend`` file that does not have a corresponding recipe with a matching
+name. To handle these errors, the best practice is to rename the ``.bbappend``
+to match the original recipe version. This also gives you the opportunity to see
+if the ``.bbappend`` is still relevant for the new version of the recipe.
+
+Another method it to use the character ``%`` in the ``.bbappend`` filename. For
+example, to append information to every ``6.*`` minor versions of the recipe
+``someapp``, the ``someapp_6.%.bbappend`` file can be created. This way, an
+error will only be triggered if the ``someapp`` recipe has a major version
+update.
+
+Finally, another method to deal with these errors is to use the variable
+:term:`BBMASK`, especially in cases where modifying the ``.bbappend`` is not
+possible.
 
 Overlaying a File Using Your Layer
 ----------------------------------
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 5d24e80865..5c2920603f 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -361,24 +361,6 @@ system and gives an overview of their function and contents.
    :term:`BB_CURRENTTASK`
       See :term:`bitbake:BB_CURRENTTASK` in the BitBake manual.
 
-   :term:`BB_DANGLINGAPPENDS_WARNONLY`
-      Defines how BitBake handles situations where an append file
-      (``.bbappend``) has no corresponding recipe file (``.bb``). This
-      condition often occurs when layers get out of sync (e.g. ``oe-core``
-      bumps a recipe version and the old recipe no longer exists and the
-      other layer has not been updated to the new version of the recipe
-      yet).
-
-      The default fatal behavior is safest because it is the sane reaction
-      given something is out of sync. It is important to realize when your
-      changes are no longer being applied.
-
-      You can change the default behavior by setting this variable to "1",
-      "yes", or "true" in your ``local.conf`` file, which is located in the
-      :term:`Build Directory`: Here is an example::
-
-         BB_DANGLINGAPPENDS_WARNONLY = "1"
-
    :term:`BB_DEFAULT_TASK`
       See :term:`bitbake:BB_DEFAULT_TASK` in the BitBake manual.