diff --git a/theme/boost/classes/autoprefixer.php b/theme/boost/classes/autoprefixer.php
index 09bc67cdbaf..59f198932c6 100644
--- a/theme/boost/classes/autoprefixer.php
+++ b/theme/boost/classes/autoprefixer.php
@@ -17,6 +17,10 @@
 /**
  * Autoprefixer.
  *
+ * This autoprefixer has been developed to satisfy the basic needs of the
+ * theme Boost when working with Bootstrap 4 alpha. We do not recommend
+ * that this tool is shared, nor used outside of this theme.
+ *
  * @package    theme_boost
  * @copyright  2016 Frédéric Massart - FMCorz.net
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
diff --git a/theme/upgrade.txt b/theme/upgrade.txt
index 9a17dd608b5..7efedcb3dbc 100644
--- a/theme/upgrade.txt
+++ b/theme/upgrade.txt
@@ -3,39 +3,39 @@ information provided here is intended especially for theme designer.
 
 === 3.2 ===
 
-* mod_chat will not display the 'course theme' option for all themes (previously it was only displayed on
-  bootstrap2 based themes).
-* A new theme config 'undeletableblocktypes' allows a theme to define which blocks are deletable.
+* Removed themes: base, canvas
+  During the upgrade process the themes will be uninstalled and all their settings will be deleted.
+  If you wish to keep your theme and its settings, download it from moodle.org and put it back in
+  the theme/ directory BEFORE UPGRADING.
+* Bootstrap 4 was added as part of a the new theme 'boost'.
+* Some backwards and forwards compatibility has been added for different bootstrap versions.
+  This is to allow the same markup to work in "clean" and "boost" themes a lot of the time.
+  It is also to allow user text with bootstrap classes to keep working in the new theme.
+* Using .dir-rtl for RTL styling is deprecated and should not be used any more. From now
+  the styles are automatically flipped when the language is right-to-left. However,
+  as this is not always perfect, you can define exceptions. Please refer to the documentation
+  of the tool RTLCSS-PHP for more information: https://github.com/moodlehq/rtlcss-php
+* Themes can now automatically compile SCSS on the fly. This works the same way as it
+  does compiling LESS on the fly, effecitvely adding $THEME->scss to your config. The
+  latter can either be the name a SCSS file (without extension) in your theme's scss/ folder,
+  or a Closure which will return the main SCSS content.
+* Two new callbacks allow themes to inject SCSS code before and after the content provided
+  by the SCSS file $THEME->scss. See $THEME->prescsscallback and $THEME->extrascsscallback.
+* A new callback can be defined to post process the CSS using an object representation
+  of the CSS tree ($THEME->csstreepostprocess). This gives a lot more flexibility than a
+  simple find and replace. Refer to 'boost' for an example, and to PHP-CSS-Parser.
+  (https://github.com/sabberworm/PHP-CSS-Parser) for the API.
 * A new core setting now enables admins to upload the logos of their site. Using the
   following methods, themers can instantly support branding logos without the need
   to implement specific theme settings:
   * $OUTPUT->get_logo_url($maxwidth, $maxheight);
   * $OUTPUT->get_compact_logo_url($maxwidth, $maxheight);
-Removed themes:
- * base, canvas
-   During the upgrade process the themes will be uninstalled and all their settings will be deleted.
-   If you wish to keep your theme and its settings, download it from moodle.org and put it back in
-   the theme/ directory BEFORE UPGRADING.
- * CLI svgtool.php has moved from theme/base/cli to admin/cli and paths should be relative to the new location.
-* Bootstrap 4 was added as part of a the new theme 'boost'.
-* Themes can now automatically compile SCSS on the fly. This works the same way as it
-  does compiling LESS on the fly, effecitvely adding $THEME->scss to your config.
-* Two new callbacks allow themes to inject SCSS code before and after the content provided
-  by the SCSS file $THEME->scss. See $THEME->prescsscallback and $THEME->extrascsscallback.
-* $THEME->scss can also be a Closure which will return the main SCSS content.
-* Using .dir-rtl for RTL styling is deprecated and should not be used any more. From now
-  the styles are automatically flipped when the language is right-to-left. However,
-  as this is not always perfect, you can define exceptions. Please refer to the documentation
-  of the tool RTLCSS-PHP for more information: https://github.com/moodlehq/rtlcss-php
 * The class .dir-ltr should not be used any more. To force LTR styles use the directive
   to remove the rule when the language is RTL. See RTLCSS-PHP for more information.
 * A new class .text-ltr may be used to force the direction to LTR. This is especially useful
   for forms fields (numbers, emails, URLs must not be RTL'd), and for displaying code
   snippets or configuration samples.
-* A new callback can be defined to post process the CSS using an object representation
-  of the CSS tree ($THEME->csstreepostprocess). This gives a lot more flexibility than a
-  simplel find and replace. Refer to 'boost' for an example, and to PHP-CSS-Parser
-  (https://github.com/sabberworm/PHP-CSS-Parser) for the API.
+* A new theme config 'undeletableblocktypes' allows a theme to define which blocks are deletable.
 * You may no longer override the following core_course_renderer methods.
   See course/upgrade.txt for more information:
   - course_modchooser_module_types
@@ -54,6 +54,9 @@ Removed themes:
   - css_is_width
   - css_sort_by_count
   - class css_optimiser no longer does anything.
+* CLI svgtool.php has moved from theme/base/cli to admin/cli and paths should be relative to the new location.
+* mod_chat will now display the 'course theme' option for all themes (previously it was only displayed on
+  bootstrap2 based themes).
 
 === 3.1 ===