Merge branch 'doc/support_policy' into 'master'

docs: Add ESP-IDF support period policy

See merge request espressif/esp-idf!6369

SUPPORT_POLICY.md

@@ -0,0 +1,66 @@
+The latest support policy for ESP-IDF can be found at [https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY.md](https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY.md)
+
+Support Period Policy
+=====================
+
+Each ESP-IDF major and minor release (V4.0, V4.1, etc) is supported for
+18 months after the initial stable release date.
+
+Supported means that the ESP-IDF team will continue to apply bug fixes,
+security fixes, etc to the release branch on GitHub, and periodically
+make new bugfix releases as needed.
+
+Users are encouraged to upgrade to a newer ESP-IDF release before the
+support period finishes and the release becomes End of Life (EOL). It is
+our policy to not continue fixing bugs in End of Life releases.
+
+Pre-release versions (betas, previews, `-rc` and `-dev` versions, etc)
+are not covered by any support period. Sometimes a particular feature is
+marked as \"Preview\" in a release, which means it is also not covered
+by the support period.
+
+The ESP-IDF Programming Guide has information about the
+[different versions of ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/latest/versions.html)
+(major, minor, bugfix, etc).
+
+Long Term Support releases
+--------------------------
+
+Some releases (starting with ESP-IDF V3.3) are designated Long Term
+Support (LTS). LTS releases are supported for 30 months (2.5 years)
+after the initial stable release date.
+
+A new LTS release will be made at least every 18 months. This means
+there will always be a period of at least 12 months to upgrade from the
+previous LTS release to the following LTS release.
+
+Example
+-------
+
+ESP-IDF V3.3 was released in September 2019 and is a Long Term Support
+(LTS) release, meaning it will be supported for 30 months until February
+2022.
+
+- The first V3.3 release was `v3.3` in September 2019.
+- The ESP-IDF team continues to backport bug fixes, security fixes,
+  etc to the release branch `release/v3.3`.
+- Periodically stable bugfix releases are created from the release
+  branch. For example `v3.3.1`, `v3.3.2`, etc. Users are encouraged to
+  always update to the latest bugfix release.
+- V3.3 bugfix releases continue until February 2022, when all V3.3.x
+  releases become End of Life.
+
+Existing Releases
+-----------------
+
+ESP-IDF release V3.3 and all newer releases will follow this support
+period policy.  The support period for each release will be announced
+when the release is made.
+
+For releases made before the support period policy was announced,
+the following support periods apply:
+
+- ESP-IDF V3.1.x and V3.2.x will both be supported until October 2020.
+- ESP-IDF V3.0.9 (planned for October 2019) will be the last V3.0
+  bugfix release. ESP-IDF V3.0.x is End of Life from October 2019.
+- ESP-IDF versions before V3.0 are already End of Life.

docs/docs_common.mk

@@ -177,9 +177,10 @@ linkcheck: | check_python_packages
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
 gh-linkcheck: | check_python_packages
-	@echo "Checking for hardcoded GitHub links"
+	@echo "Checking for hardcoded GitHub links"  # note: exception for links to support policy doc as we *want* this to be a link to master's policy
 	@if (find ../ -name '*.rst' | xargs grep \
-		'https://github.com/espressif/esp-idf/tree\|https://github.com/espressif/esp-idf/blob\|https://github.com/espressif/esp-idf/raw'\
+		'https://github.com/espressif/esp-idf/tree\|https://github.com/espressif/esp-idf/blob\|https://github.com/espressif/esp-idf/raw' \
+		| grep -v 'SUPPORT_POLICY\.md' \
 		); \
 	then \
 		echo "WARNINIG: Some .rst files contain hardcoded Github links."; \

docs/en/api-reference/system/system.rst

@@ -104,6 +104,8 @@ Chip version
 
 :cpp:func:`esp_chip_info` function fills :cpp:class:`esp_chip_info_t` structure with information about the chip. This includes the chip revision, number of CPU cores, and a bit mask of features enabled in the chip.
 
+.. _idf-version-h:
+
 SDK version
 -----------
 

docs/en/versions.rst

@@ -31,13 +31,14 @@ Which Version Should I Start With?
 
 - For production purposes, use the `current stable version`_. Stable versions have been manually tested, and are updated with "bugfix releases" which fix bugs without changing other functionality (see `Versioning Scheme`_ for more details).
 
+  In order to maximize the time between updates to new ESP-IDF versions, use the latest stable Long Term Support release version. This version can be found on the `Releases page`_.
+
 - For prototyping, experimentation or for developing new ESP-IDF features, use the `latest version (master branch in Git) <https://docs.espressif.com/projects/esp-idf/en/latest/>`_. The latest version in the master branch has all the latest features and has passed automated testing, but has not been completely manually tested ("bleeding edge").
 
 - If a required feature is not yet available in a stable release, but you do not want to use the master branch, it is possible to check out a pre-release version or a release branch. It is recommended to start from a stable version and then follow the instructions for :ref:`updating-pre-release` or :ref:`updating-release-branch`.
 
 See :ref:`updating` if you already have a local copy of ESP-IDF and wish to update it.
 
-
 Versioning Scheme
 -----------------
 
@@ -55,6 +56,22 @@ ESP-IDF uses `Semantic Versioning <http://semver.org/>`_. This means that:
 
   If updating to a new bugfix release (for example, from ``v3.0`` to ``v3.0.1``), you do not need to change any code in your project, and you only need to re-test the functionality directly related to bugs listed in the release notes on the `Releases page`_.
 
+Support Periods
+---------------
+
+Each ESP-IDF major and minor release version has an associated support period. After this period, the release is End of Life and no longer supported. Some releases are designated Long Term Support, which means the support period is longer than for other releases.
+
+The `ESP-IDF Support Period Policy`_ explains this in detail, and describes how the support periods for each release are determined.
+
+Each release on the `Releases page`_ includes information about the support period for that particular release.
+
+As a general guideline:
+
+- Using Long Term Support releases will maximize the amount of time between required ESP-IDF major or minor upgrades.
+- Using standard stable releases will require more frequent upgrades to new ESP-IDF versions. However, this means that new features and major improvements will be available more frequently.
+
+It is also possible to upgrade from a Long Term Support release to a standard release, and vice versa.
+
 
 Checking the Current Version
 ----------------------------
@@ -65,6 +82,8 @@ The local ESP-IDF version can be checked by using idf.py::
 
 The ESP-IDF version is also compiled into the firmware and can be accessed (as a string) via the macro ``IDF_VER``. The default ESP-IDF bootloader will print the version on boot (the version information is not always updated in code, it only changes if that particular source file is recompiled).
 
+If writing code that needs to support multiple ESP-IDF versions, the version can be checked at compile time using :ref:`compile-time macros<idf-version-h>`.
+
 Examples of ESP-IDF versions:
 
 ============================ =====================================================================================
@@ -190,3 +209,4 @@ Each time you ``git pull`` this branch, ESP-IDF will be updated with fixes for t
 .. _`list of branches`: https://github.com/espressif/esp-idf/branches
 .. _`list of tags`: https://github.com/espressif/esp-idf/tags
 .. _`current stable version`: https://docs.espressif.com/projects/esp-idf/en/stable/
+.. _`ESP-IDF Support Period Policy`:  https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY.md