diff --git a/core/lib/Drupal/Core/Config/ConfigEvents.php b/core/lib/Drupal/Core/Config/ConfigEvents.php
index 794fbc5..92fa18c 100644
--- a/core/lib/Drupal/Core/Config/ConfigEvents.php
+++ b/core/lib/Drupal/Core/Config/ConfigEvents.php
@@ -10,6 +10,15 @@
 /**
  * Defines events for the configuration system.
  *
+ * These events will be fired when configuration is manipulated by
+ * hook_update_N() implementations. Subscribers for these events can not make
+ * any assumption that the config data is valid and should ensure that their
+ * actions are safe regardless of the structure of the underlying configuration.
+ * The following actions are examples that are safe:
+ * - Cache invalidation.
+ * - Enforcing related config change.
+ * - Marking a container for rebuild.
+ *
  * @see \Drupal\Core\Config\ConfigCrudEvent
  */
 final class ConfigEvents {