alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs: Update Versions file in line with the latest Support Policy document

Browse Source
This commit is contained in:
Angus Gratton 2020-08-27 10:09:53 +10:00
parent 7402e17838
commit dbdb1c1c23
3 changed files with 30 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/build_docs.py
View File

@ -401,8 +401,9 @@ def call_linkcheck(entry):
# https://github.com/espressif/esp-idf/raw/
GH_LINK_RE = r"https://github.com/espressif/esp-idf/(?:tree|blob|raw)/[^\s]+"
# we allow this one link, because we always want users to see the latest support policy
GH_LINK_ALLOWED = ["https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY.md"]
# we allow this one doc, because we always want users to see the latest support policy
GH_LINK_ALLOWED = ["https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY.md",
"https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY_CN.md"]
def action_gh_linkcheck(args):

18
docs/en/versions.rst
View File

@ -29,9 +29,7 @@ Another place to find documentation for all releases is the documentation page,
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 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). Every stable release 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").
@ -59,7 +57,7 @@ ESP-IDF uses `Semantic Versioning <http://semver.org/>`_. This means that:
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.
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.
The `ESP-IDF Support Period Policy`_ explains this in detail, and describes how the support periods for each release are determined.
@ -67,10 +65,10 @@ Each release on the `Releases page`_ includes information about the support peri
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.
- If starting a new project, use the latest stable release.
- If you have a GitHub account, click the "Watch" button in the top-right of the `Releases page`_ and choose "Releases only". GitHub will notify you whenever a new release is available. Whenever a bug fix release is available for the version you are using, plan to update to it.
- If possible, periodically update the project to a new major or minor ESP-IDF version (for example, once a year.) The update process should be straightforward for Minor updates, but may require some planning and checking of the release notes for Major updates.
- Always plan to update to a newer release before the release you are using becomes End of Life.
Checking the Current Version
@ -80,7 +78,7 @@ The local ESP-IDF version can be checked by using idf.py::
idf.py --version
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).
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 if the code in the GitHub repo is updated, it only changes if there is a clean build or 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>`.
@ -93,7 +91,7 @@ Version String Meaning
| - ``v3.2-dev`` - in development for version 3.2.
| - ``306`` - number of commits after v3.2 development started.
| - ``beb3611ca`` - commit identifier.
``v3.0.2`` Stable release, tagged ``v3.0.2``.
``v3.0.2`` | Stable release, tagged ``v3.0.2``.
``v3.1-beta1-75-g346d6b0ea`` | Beta version in development (on a :ref:`release branch <updating-release-branch>`).
| - ``v3.1-beta1`` - pre-release tag.
| - ``75`` - number of commits after the pre-release beta tag was assigned.

21
docs/zh_CN/versions.rst
View File

@ -27,7 +27,7 @@ ESP-IDF 在 GitHub 平台上的完整发布历史请见 `发布说明页面`_。
我该选择哪个版本？
----------------------------------
- 如有量产需求，请使用 `最新稳定版本`_。稳定版本已通过人工测试，后续更新仅修复 bug，主要特性不受影响（更多详情，请见 `版本管理`_）。
- 如有量产需求，请使用 `最新稳定版本`_ 。稳定版本已通过人工测试，后续更新仅修复 bug，主要特性不受影响（更多详情，请见 `版本管理`_ ）。请访问 `发布说明页面`_ 界面查看每一个稳定发布版本。
- 如需尝试/测试 ESP-IDF 的最新特性，请使用 `最新版本（在 master 分支上） <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/>`_。最新版本包含 ESP-IDF 的所有最新特性，已通过自动化测试，但尚未全部完成人工测试（因此存在一定风险）。
@ -53,6 +53,21 @@ ESP-IDF 采用了 `语义版本管理方法 <http://semver.org/>`_，即您可
升级至一个新的 Bugfix 版本（例 ``v3.0`` 升级至 ``v3.0.1``）意味着您不需要更新您的工程代码，仅需测试与本次发布修复 bug（列表见 `发布说明页面`_）直接相关的特性。
支持期限
---------------
ESP-IDF 的每个主要版本和次要版本都有相应的支持期限。支持期限满后，版本停止更新维护，将不再支持。
`支持期限政策`_ 对此有具体描述，并介绍了每个版本的支持期限是如何界定的。
`发布说明页面`_ 界面上的每一个发布版本都提供了该版本的支持期限信息。
一般而言：
- 如您刚开始一个新项目，建议使用最新稳定版本。
- 如您有 GitHub 账号，请点击 `发布说明页面`_ 界面右上角的 "Watch" 按键，并选中 "Releases only" 选项。GitHub 将会在新版本发布的时候通知您。当您所使用的版本有 bugfix 版本发布时，请做好升级至该 bugfix 版本的规划。
- 如可能，请定期（如每年一次）将项目的 IDF 版本升级至一个新的主要版本或次要版本。对于小版本更新，更新过程应该比较简单，但对于主要版本更新，可能需要细致查看发布说明并做对应的更新规划。
- 请确保您所使用的版本停止更新维护前，已做好升级至新版本的规划。
查看当前版本
----------------------------
@ -61,7 +76,7 @@ ESP-IDF 采用了 `语义版本管理方法 <http://semver.org/>`_，即您可
idf.py --version
此外，由于 ESP-IDF 的版本也已编译至固件中，因此您也可以使用宏 ``IDF_VER`` 查看 ESP-IDF 的版本（以字符串的格式）。ESP-IDF 默认引导程序可以在设备启动时打印 ESP-IDF 的版本，但注意代码中的版本信息仅会在源代码重新编译时才会更新，因此打印出来的版本可能并不是最新的。
此外，由于 ESP-IDF 的版本也已编译至固件中，因此您也可以使用宏 ``IDF_VER`` 查看 ESP-IDF 的版本（以字符串的格式）。ESP-IDF 默认引导程序会在设备启动时打印 ESP-IDF 的版本。请注意，在 GitHub 仓库中的代码更新时，代码中的版本信息仅会在源代码重新编译或在清除编译时才会更新，因此打印出来的版本可能并不是最新的。
几个 ESP-IDF 版本的例子：
@ -188,3 +203,5 @@ Git 工作流
.. _`分支列表`: https://github.com/espressif/esp-idf/branches
.. _`标签列表`: https://github.com/espressif/esp-idf/tags
.. _`最新稳定版本`: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/
.. _`支持期限政策`: https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY_CN.md
.. _`版本管理`: https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/versions.html