diff --git a/theme/upgrade.txt b/theme/upgrade.txt
index 8c9d3768232..12d9e5bc016 100644
--- a/theme/upgrade.txt
+++ b/theme/upgrade.txt
@@ -13,6 +13,10 @@ information provided here is intended especially for theme designer.
 * The functions search_listing() and search_pagination() in the core_course_management_renderer class take the searched string
   as an extra parameter - see MDL-46902.
 * Themes with non-fixed headers must have the .navbar class in their navbar in order for floating headers in the grader report to work - see MDL-46658.
+* To accomodate the new gradebook, use of overflow: hidden or overflow-x: hidden CSS rules on DOM elements containing the
+  #user-grades table, visible at [Course administration -> Grades] is not recommended. Please use overflow: auto or
+  overflow: scroll instead, as this will handle medium to large courses with multiple activities better (more information available at https://docs.moodle.org/dev/Theme_upgrade_notes ).
+* The new user menu can be added to themes by calling $OUTPUT->user_menu(); we recommend doing so in a backwards-compatible way (see https://docs.moodle.org/dev/Theme_upgrade_notes for more information).
 
 === 2.7 ===