diff --git a/UPGRADING.md b/UPGRADING.md
index d950d9997fb..535d588019a 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -15,6 +15,14 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
 - The `\core\attribute\deprecated` attribute constructor `$replacement` parameter now defaults to null, and can be omitted
 
   For more information see [MDL-84531](https://tracker.moodle.org/browse/MDL-84531)
+- Added a new `\core\deprecation::emit_deprecation()` method which should be used in places where a deprecation is known to occur. This method will throw debugging if no deprecation notice was found, for example:
+  ```php
+  public function deprecated_method(): void {
+      \core\deprecation::emit_deprecation([self::class, __FUNCTION__]);
+  }
+  ```
+
+  For more information see [MDL-85897](https://tracker.moodle.org/browse/MDL-85897)
 
 ### core_message
 
diff --git a/lib/UPGRADING.md b/lib/UPGRADING.md
index a5ef00441a5..bd88040f246 100644
--- a/lib/UPGRADING.md
+++ b/lib/UPGRADING.md
@@ -7,6 +7,14 @@
 - The `\core\attribute\deprecated` attribute constructor `$replacement` parameter now defaults to null, and can be omitted
 
   For more information see [MDL-84531](https://tracker.moodle.org/browse/MDL-84531)
+- Added a new `\core\deprecation::emit_deprecation()` method which should be used in places where a deprecation is known to occur. This method will throw debugging if no deprecation notice was found, for example:
+  ```php
+  public function deprecated_method(): void {
+      \core\deprecation::emit_deprecation([self::class, __FUNCTION__]);
+  }
+  ```
+
+  For more information see [MDL-85897](https://tracker.moodle.org/browse/MDL-85897)
 
 ## 4.5.5