From b5500150933c16c89f1327c184475b9622a90b33 Mon Sep 17 00:00:00 2001
From: Jan Prochazka <90197375+P-R-O-C-H-Y@users.noreply.github.com>
Date: Mon, 25 Mar 2024 13:06:52 +0100
Subject: [PATCH 1/3] docs(): Add core compatibility guide

---
 docs/en/guides/core_compatibility.rst | 40 +++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 docs/en/guides/core_compatibility.rst

diff --git a/docs/en/guides/core_compatibility.rst b/docs/en/guides/core_compatibility.rst
new file mode 100644
index 00000000000..aaa6785dd80
--- /dev/null
+++ b/docs/en/guides/core_compatibility.rst
@@ -0,0 +1,40 @@
+Compatibility Guide for ESP32 Arduino Core
+====================================================
+
+Introduction
+------------
+
+Welcome to the compatibility guide for library developers aiming to support multiple versions of the ESP32 Arduino core. This documentation provides essential tips and best practices for ensuring compatibility with 2.x, 3.x and future versions of the ESP32 Arduino core.
+
+Code Adaptations
+----------------
+
+To ensure compatibility with both versions of the ESP32 Arduino core, developers should utilize conditional compilation directives in their code. Below is an example of how to conditionally include code based on the ESP32 Arduino core version::
+
+    .. code-block:: cpp
+
+      #if ESP_ARDUINO_VERSION >= ESP_ARDUINO_VERSION_VAL(3, 0, 0)
+        // Code for ESP32 Arduino core version 3.x
+      #else
+        // Code for ESP32 Arduino core version 2.x
+      #endif
+
+Version Print
+-------------
+
+To easily print the ESP32 Arduino core version at runtime, developers can use the `ESP_ARDUINO_VERSION_STR` macro. Below is an example of how to print the ESP32 Arduino core version::
+
+    .. code-block:: cpp
+
+      Serial.printf(" ESP32 Arduino core version: %s\n", ESP_ARDUINO_VERSION_STR);
+
+API Differences
+---------------
+
+Developers should be aware, that there may be API differences between major versions of the ESP32 Arduino core. For this we created a `Migration guide <https://docs.espressif.com/projects/arduino-esp32/en/latest/migration_guides.html>`_. to help developers transition from between major versions of the ESP32 Arduino core.
+
+Library Testing
+---------------
+
+We have added an External Library Test CI job, which tests external libraries with the latest version of the ESP32 Arduino core to help developers ensure compatibility with the latest version of the ESP32 Arduino core.
+If you want to include your library in the External Library Test CI job, please follow the instructions in the `External Libraries Test <https://docs.espressif.com/projects/arduino-esp32/en/latest/esp32/external_libraries_test.html>`_.

From 45dbabb31ef1b0e22c0b345a0d246696c7b61d0b Mon Sep 17 00:00:00 2001
From: Jan Prochazka <90197375+P-R-O-C-H-Y@users.noreply.github.com>
Date: Tue, 26 Mar 2024 11:03:52 +0100
Subject: [PATCH 2/3] Update core_compatibility.rst

---
 docs/en/guides/core_compatibility.rst | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/en/guides/core_compatibility.rst b/docs/en/guides/core_compatibility.rst
index aaa6785dd80..6ed7c79e7d8 100644
--- a/docs/en/guides/core_compatibility.rst
+++ b/docs/en/guides/core_compatibility.rst
@@ -13,10 +13,14 @@ To ensure compatibility with both versions of the ESP32 Arduino core, developers
 
     .. code-block:: cpp
 
+      #ifdef ESP_ARDUINO_VERSION_MAJOR
       #if ESP_ARDUINO_VERSION >= ESP_ARDUINO_VERSION_VAL(3, 0, 0)
-        // Code for ESP32 Arduino core version 3.x
+          // Code for version 3.x
       #else
-        // Code for ESP32 Arduino core version 2.x
+          // Code for version 2.x
+      #endif
+      #else
+          // Code for version 1.x
       #endif
 
 Version Print

From c197e59e7feae37cd5f029f9cc0002f4e70a0ee8 Mon Sep 17 00:00:00 2001
From: Jan Prochazka <90197375+P-R-O-C-H-Y@users.noreply.github.com>
Date: Wed, 27 Mar 2024 08:08:21 +0100
Subject: [PATCH 3/3] Update core_compatibility.rst

---
 docs/en/guides/core_compatibility.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/en/guides/core_compatibility.rst b/docs/en/guides/core_compatibility.rst
index 6ed7c79e7d8..cb530ac5e7c 100644
--- a/docs/en/guides/core_compatibility.rst
+++ b/docs/en/guides/core_compatibility.rst
@@ -1,5 +1,5 @@
 Compatibility Guide for ESP32 Arduino Core
-====================================================
+==========================================
 
 Introduction
 ------------