diff --git a/esphome/core/config.py b/esphome/core/config.py
index 6bd8c6be0e..c6404fc6de 100644
--- a/esphome/core/config.py
+++ b/esphome/core/config.py
@@ -69,6 +69,13 @@ validate_platform = cv.one_of(*ESP_PLATFORMS, upper=True)
 
 PLATFORMIO_ESP8266_LUT = {
     **ARDUINO_VERSION_ESP8266,
+    # Keep this in mind when updating the recommended version:
+    #  * New framework historically have had some regressions, especially for WiFi, BLE and the
+    #    bootloader system. The new version needs to be thoroughly validated before changing the
+    #    recommended version as otherwise a bunch of devices could be bricked
+    #  * The docker images need to be updated to ship the new recommended version, in order not
+    #    to DDoS platformio servers.
+    #    Update this file: https://github.com/esphome/esphome-docker-base/blob/master/platformio.ini
     "RECOMMENDED": ARDUINO_VERSION_ESP8266["2.7.4"],
     "LATEST": "espressif8266",
     "DEV": ARDUINO_VERSION_ESP8266["dev"],
@@ -76,6 +83,7 @@ PLATFORMIO_ESP8266_LUT = {
 
 PLATFORMIO_ESP32_LUT = {
     **ARDUINO_VERSION_ESP32,
+    # See PLATFORMIO_ESP8266_LUT for considerations when changing the recommended version
     "RECOMMENDED": ARDUINO_VERSION_ESP32["1.0.6"],
     "LATEST": "espressif32",
     "DEV": ARDUINO_VERSION_ESP32["dev"],