Api Stability - Espressif ESP32-S2 Programming Manual

Chapter 2. API Reference
in mind, and might not include all the error handling required for production applications. Take time to read the code
and understand if it applicable to your use case.

2.7.5 API Stability

ESP-IDF uses Semantic Versioning
Minor and bugfix releases of ESP-IDF guarantee compatibility with previous releases. The sections below explain
different aspects and limitations to compatibility.
Source level compatibility
ESP-IDF guarantees source level compatibility of C functions, structures, enums, type definitions and preprocessor
macros declared in public header files of ESP-IDF components. Source level compatibility implies that the application
can be recompiled with the newer version of ESP-IDF without changes.
The following changes are allowed between minor versions and do not break source level compatibility:
• Deprecating functions (using the deprecated attribute) and header files (using a preprocessor #warning).
Deprecations are listed in ESP-IDF relese notes. It is recommended to update the source code to use the newer
functions or files that replace the deprecated ones, however this is not mandatory. Deprecated functions and
files can be removed in major versions of ESP-IDF.
• Renaming components, moving source and header files between components —provided that the build system
ensures that correct files are still found.
• Renaming Kconfig options. Kconfig system
names can still be used by the application in sdkconfig file, CMake files and source code.
Lack of binary compatibility
ESP-IDF does not guarantee binary compatibility between releases. This means that if a precompiled library is built
with one ESP-IDF version, it is not guaranteed to work the same way with the next minor or bugfix release. The
following are the possible changes that keep source level compatibility but not binary compatibility:
• Changing numerical values for C enum members.
• Adding new structure members or changing the order of members. See
help ensure compatibility.
• Replacing an extern function with a static inline one with the same signature, or vice versa.
• Replacing a function-like macro with a compatible C function.
Other exceptions from compatibility
While we try to make upgrading to a new ESP-IDF version easy, there are parts of ESP-IDF that may change between
minor versions in an incompatible way. We appreciate issue reports about any unintended breaking changes that don'
t fall into the categories below.
• Private APIs.
• Components in example
• Features clearly marked as "beta", "preview", or "experimental".
• Changes made to mitigate security issues or to replace insecure default behaviors with a secure ones.
• Features which were never functional. For example, if it was never possible to use a certain function or an
enumeration value, it may get renamed (as part of fixing it) or removed. This includes software features which
depend on non-functional chip hardware features.
• Unexpected or undefined behavior (for example, due to missing validation of argument ranges) that is not
documented explicitly may be fixed/changed.
• Location of Kconfig
• Location and names of example projects.
Espressif Systems
as explained in the
renaming mechanism
projects.
options in menuconfig.
Submit Document Feedback
versions page.
ensures that the original Kconfig option
Configuration structures
1057
for tips that
Release v4.4