diff --git a/docs/changelog.rst b/docs/changelog.rst
index 6eb61c1e..29350eb1 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -8,6 +8,14 @@ Release history
 * Fix bug in which all static files were processed as "draft"
 * Bug fixes for Invoke/Makefile automation, Importer, and other miscellanea
 
+If upgrading from 3.7.x or earlier, please note that slug-related settings in
+4.0+ use ``{slug}`` and/or ``{lang}`` rather than ``%s``. If ``%s``-style
+settings are encountered, Pelican will emit a warning and fall back to the
+default setting. Some user-submitted themes might try to format setting values
+but fail upon site build with a ``TypeError``. In such cases, the theme needs
+to be updated. For example, instead of ``TAG_FEED_ATOM|format(tag.slug)``, use
+``TAG_FEED_ATOM|format(slug=tag.slug)``
+
 4.0.0 (2018-11-13)
 ==================