docs: Kconfig formatting rules and backward compatibility of options

docs/en/api-reference/kconfig.rst

@@ -15,6 +15,54 @@ When updating ESP-IDF version, it is not uncommon to find that new Kconfig optio
 
 In some cases, such as when ``sdkconfig`` file is under revision control, the fact that ``sdkconfig`` file gets changed by the build system may be inconvenient. The build system offers a way to avoid this, in the form of ``sdkconfig.defaults`` file. This file is never touched by the build system, and must be created manually. It can contain all the options which matter for the given application. The format is the same as that of the ``sdkconfig`` file. Once ``sdkconfig.defaults`` is created, ``sdkconfig`` can be deleted and added to the ignore list of the revision control system (e.g. ``.gitignore`` file for git). Project build targets will automatically create ``sdkconfig`` file, populated with the settings from ``sdkconfig.defaults`` file, and the rest of the settings will be set to their default values. Note that when ``make defconfig`` is used, settings in sdkconfig will be overriden by the ones in ``sdkconfig.defaults``. For more information, see :ref:`custom-sdkconfig-defaults`.
 
+Kconfig Formatting Rules
+========================
+
+The following attributes of ``Kconfig`` files are standardized:
+
+- Within any menu, option names should have a consistent prefix. The prefix length is currently set to at least 3
+  characters.
+- The indentation style is 4 characters created by spaces. All sub-items belonging to a parent item are indented by
+  one level deeper. For example, ``menu`` is indented by 0 characters, the ``config`` inside of the menu by 4
+  characters, the help of the ``config`` by 8 characters and the text of the ``help`` by 12 characters.
+- No trailing spaces are allowed at the end of the lines.
+- The maximum length of options is set to 40 characters.
+- The maximum length of lines is set to 120 characters.
+- Lines cannot be wrapped by backslash (because there is a bug in earlier versions of ``conf-idf`` which causes that
+  Windows line endings are not recognized after a backslash).
+
+Format checker
+--------------
+
+``tools/check_kconfigs.py`` is provided for checking the ``Kconfig`` formatting
+rules. The checker checks all ``Kconfig`` and ``Kconfig.projbuild`` files in
+the ESP-IDF directory and generates a new file with suffix ``.new`` with some
+recommendations how to fix issues (if there are any). Please note that the
+checker cannot correct all rules and the responsibility of the developer is to
+check and make final corrections in order to pass the tests. For example,
+indentations will be corrected if there isn't some misleading previous
+formatting but it cannot come up with a common prefix for options inside a
+menu.
+
+Backward Compatibility of Kconfig Options
+=========================================
+
+The standard Kconfig_ tools ignore unknown options in ``sdkconfig``. So if a
+developer has custom settings for options which are renamed in newer ESP-IDF
+releases then the given setting for the option would be silently ignored.
+Therefore, several features have been adopted to avoid this:
+
+1. ``confgen.py`` is used by the tool chain to pre-process ``sdkconfig`` files before anything else, for example
+   ``menuconfig``, would read them. As the consequence, the settings for old options will be kept and not ignored.
+2. ``confgen.py`` recursively finds all ``sdkconfig.rename`` files in ESP-IDF directory which contain old and new
+   ``Kconfig`` option names. Old options are replaced by new ones in the ``sdkconfig`` file.
+3. ``confgen.py`` post-processes ``sdkconfig`` files and generates all build
+   outputs (``sdkconfig.h``, ``sdkconfig.cmake``, ``auto.conf``) by adding a list
+   of compatibility statements, i.e. value of the old option is set the value of
+   the new option (after modification). This is done in order to not break
+   customer codes where old option might still be used.
+4. :ref:`configuration-deprecated-options` are automatically generated by ``confgen.py``.
+
 .. _configuration-options-reference:
 
 Configuration Options Reference

tools/kconfig_new/confgen.py

@@ -122,7 +122,7 @@ class DeprecatedOptions(object):
         if len(self.r_dic) > 0:
             with open(path_output, 'a') as f_o:
                 header = 'Deprecated options and their replacements'
-                f_o.write('{}\n{}\n\n'.format(header, '-' * len(header)))
+                f_o.write('.. _configuration-deprecated-options:\n\n{}\n{}\n\n'.format(header, '-' * len(header)))
                 for dep_opt in sorted(self.r_dic):
                     new_opt = self.r_dic[dep_opt]
                     if new_opt not in config.syms or (config.syms[new_opt].choice is None and option_was_written(new_opt)):