diff --git a/lib/upgrade.txt b/lib/upgrade.txt
index 7a0dd3da2b9..2d4524d1d17 100644
--- a/lib/upgrade.txt
+++ b/lib/upgrade.txt
@@ -17,6 +17,10 @@ information provided here is intended especially for developers.
 * For plugins that override secondary navigation, the namespace for the custom secondary navigation class has
   changed. It was (for example) mod_mymodule\local\views\secondary but is now
   mod_mymodule\navigation\views\secondary. The old location will continue to work, but is deprecated.
+* The check for $plugin->incompatible was found to be incorrect. The $plugin->incompatible attribute is meant to define the minimum
+  Moodle version the plugin is incompatible with but the implemented logic for the check was the opposite. Plugins declaring this
+  attribute may encounter different behaviours between older Moodle versions (<v3.11.8, <v4.0.2) and the later ones. We recommend
+  plugin developers to not use this attribute for Moodle versions 4.0 and below in order to avoid this problem.
 
 === 4.0 ===