From 0caabec88f2a24f29293a42d622331ecfbe0deee Mon Sep 17 00:00:00 2001 From: Natasha Date: Fri, 10 May 2019 19:17:49 +0800 Subject: [PATCH] Add translation for version file --- docs/en/versions.rst | 2 + docs/zh_CN/versions.rst | 192 +++++++++++++++++++++++++++++++++++++++- 2 files changed, 193 insertions(+), 1 deletion(-) diff --git a/docs/en/versions.rst b/docs/en/versions.rst index 331c6e9d0c..a1cd3ece6c 100644 --- a/docs/en/versions.rst +++ b/docs/en/versions.rst @@ -1,6 +1,8 @@ ESP-IDF Versions ================ +:link_to_translation:`zh_CN:[中文]` + The ESP-IDF GitHub repository is updated regularly, especially the master branch where new development takes place. For production use, there are also stable releases available. diff --git a/docs/zh_CN/versions.rst b/docs/zh_CN/versions.rst index e060a86d88..31ba158eab 100644 --- a/docs/zh_CN/versions.rst +++ b/docs/zh_CN/versions.rst @@ -1 +1,191 @@ -.. include:: ../en/versions.rst +ESP-IDF 版本简介 +================ + +:link_to_translation:`en:[English]` + +ESP-IDF 的 GitHub 仓库时常更新，特别是用于开发新特性的 master 分支。 + +如有量产需求，请使用稳定版本。 + + +发布版本 +--------- + +您可以通过以下链接访问各个版本的配套文档： + +* 最新稳定版 ESP-IDF：https://docs.espressif.com/projects/esp-idf/zh_CN/stable/ + +* 最新版 ESP-IDF（即 master 分支）：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/ + +ESP-IDF 在 GitHub 平台上的完整发布历史请见 `发布说明页面`_。您可以在该页面查看各个版本的发布说明、配套文档及相应获取方式。 + +此外，您还可以直接前往文档页面，查看部分 ESP-IDF 版本的配套文档，具体可通过点击页面左下角的小三角标志，在不同版本间切换。 + +.. image:: /../_static/choose_version.png + + +我该选择哪个版本？ +---------------------------------- + +- 如有量产需求，请使用 `最新稳定版本`_。稳定版本已通过人工测试，后续更新仅修复 bug，主要特性不受影响（更多详情，请见 `版本管理`_）。 + +- 如需尝试/测试 ESP-IDF 的最新特性，请使用 `最新版本（在 master 分支上） `_。最新版本包含 ESP-IDF 的所有最新特性，已通过自动化测试，但尚未全部完成人工测试（因此存在一定风险）。 + +- 如需使用稳定版本中没有的新特性，但同时又不希望受到 master 分支更新的影响，您可以将一个最适合您的稳定版本 :ref:`更新至一个预发布版本` 或 :ref:`更新至一个发布分支`。 + +有关如何更新 ESP-IDF 本地副本的内容，请参考 :ref:`updating` 章节。 + + +版本管理 +----------------- + +ESP-IDF 采用了 `语义版本管理方法 `_，即您可以从字面含义理解每个版本的差异。其中 + +- 主要版本（例 ``v3.0``）代表有重大更新，包括增加新特性、改变现有特性及移除已弃用的特性。 + + 升级至一个新的主要版本（例 ``v2.1`` 升级至 ``v3.0``）意味着您可能需要更新您的工程代码，并重新测试您的工程，具体可参考 `发布说明页面`_ 的重大变更 (Breaking Change) 部分。 + +- 次要版本（例 ``v3.1``）代表有新增特性和 bug 修复，但现有特性不受影响，公开 API 的使用也不受影响。 + + 升级至一个新的次要版本（例 ``v3.0`` 升级至 ``v3.1``）意味着您可能不需要更新您的工程代码，但需重新测试您的工程，特别是 `发布说明页面`_ 中专门提到的部分。 + +- Bugfix 版本（例 ``v3.0.1``）仅修复 bug，并不增加任何新特性。 + + 升级至一个新的 Bugfix 版本（例 ``v3.0`` 升级至 ``v3.0.1``）意味着您不需要更新您的工程代码，仅需测试与本次发布修复 bug（列表见 `发布说明页面`_）直接相关的特性。 + + +查看当前版本 +---------------------------- + +查看 ESP-IDF 本地副本的版本，请使用 git 命令:: + + cd $IDF_PATH + git describe --tags --dirty + +此外，由于 ESP-IDF 的版本也已编译至固件中，因此您也可以使用宏 ``IDF_VER`` 查看 ESP-IDF 的版本（以字符串的格式）。ESP-IDF 默认引导程序可以在设备启动时打印 ESP-IDF 的版本，但注意代码中的版本信息仅会在源代码重新编译时才会更新，因此打印出来的版本可能并不是最新的。 + +几个 ESP-IDF 版本的例子： + +=============================== =================================================================================================== +版本字符串 含义 +=============================== =================================================================================================== +``v3.2-dev-306-gbeb3611ca`` | master 分支上的预发布版本。 + | - ``v3.2-dev``：为 v3.2 进行的开发。 + | - ``306``：v3.2 开发启动后的 commit 数量。 + | - ``beb3611ca``：commit 标识符。 +``v3.0.2`` 稳定版本，标签为 ``v3.0.2``。 +``v3.1-beta1-75-g346d6b0ea`` | v3.1 的 beta 测试版本（可参考 :ref:`更新至一个发布分支`）。 + | - ``v3.1-beta1`` - 预发布标签。 + | - ``75``：添加预发布 beta 标签后的 commit 数量。 + | - ``346d6b0ea``：commit 标识符。 + +``v3.0.1-dirty`` | 稳定版本，标签为 ``v3.0.1``。 + | - ``dirty`` 代表 ESP-IDF 的本地副本有修改。 +=============================== =================================================================================================== + + +Git 工作流 +------------ + +乐鑫 ESP-IDF 团队的 (Git) 开发工作流程如下： + +- 新的改动总是在 master 分支（最新版本）上进行。master 分支上的 ESP-IDF 版本总带有 ``-dev`` 标签，表示“正在开发中”，例 ``v3.1-dev``。 +- 这些改动将首先在乐鑫的内部 Git 仓库进行代码审阅与测试，而后在自动化测试完成后推至 GitHub。 +- 新版本一旦完成特性开发（在 ``master`` 分支上进行）并达到进入 beta 测试的标准，则将该版本签出至一个新分支（例 ``release/v3.1``）。此外，该分支还打上预发布标签（例 ``v3.1-beta1``）。您可以在 GitHub 平台上查看 ESP-IDF 的完整 `分支列表`_ 和 `标签列表`_。Beta 预发布版本可能仍存在大量“已知问题”(Known Issue)。 +- 随着对 beta 版本的不断测试，bug 修复将同时增加至该发布分支和 ``master`` 分支。而且，``master`` 分支可能也已经开始为下个版本开发新特性了。 +- 当测试快结束时，该发布分支上将增加一个 rc 标签，代表候选发布 (Release Candidate) ，例 ``v3.1-rc1``。此时，该分支仍属于预发布版本。 +- 如果一直未发现或报告重大 bug，则该预发布版本将最终增加“主要版本”（例 ``v4.0``）或“次要版本”标记（例 ``v3.1``），成为正式发布版本，并体现在 `发布说明页面`_ 。 +- 后续，该版本中发现的 bug 都将在该发布分支上进行修复。人工测试完成后，该分支将增加一个 bugfix 版本标签（例 ``v3.1.1``），并体现在 `发布说明页面`_ 。 + + +.. _updating: + +更新 ESP-IDF +---------------- + +请根据您的实际情况，对 ESP-IDF 进行更新。 + +- 如有量产用途，建议参考 :ref:`更新至一个稳定发布版本`。 +- 如需测试/研发/尝试最新特性，建议参考 :ref:`更新至 master 分支` 。 +- 两者折衷建议参考 :ref:`更新至一个发布分支`。 + +.. note:: 在参考本指南时，请首先获得 ESP-IDF 的本地副本，具体步骤请参考 :doc:`入门指南 ` 中的介绍。 + + +.. _`更新至一个稳定发布版本`: + +更新至一个稳定发布版本 +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +（推荐量产用户）如需更新至一个新的 ESP-IDF 发布版本，请参考以下步骤： + +- 请定期查看 `发布说明页面`_ ，了解最新发布情况。 +- 如有新发布的 bugfix 版本（例 ``v3.0.1`` 或 ``v3.0.2``）时，请将新的 bugfix 版本更新至您的 ESP-IDF 目录： + +.. code-block:: bash + + cd $IDF_PATH + git fetch + git checkout vX.Y.Z + git submodule update --init --recursive + +- 如有主要版本或次要版本新发布时，请查看发布说明中的具体描述，并决定是否升级您的版本。具体命令与上方描述一致。 + +.. note:: 如果您之前在安装 ESP-IDF 时使用了 zip 文件包，而非通过 Git 命令，则您将无法使用 Git 命令进行版本升级，此属正常情况。这种情况下，请重新下载最新 zip 文件包，并替换掉之前 ``IDF_PATH`` 下的全部内容。 + + +.. _`更新至一个预发布版本`: + +更新至一个预发布版本 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +您也可以将您的本地副本签出（命令 ``git checkout``）至一个预发布版本或 rc 版本，具体方法请参考 :ref:`更新至一个稳定发布版本` 中的描述。 + +预发布版本通常不体现在 `发布说明页面`_。更多详情，请查看完整 `标签列表`_。使用预发布版本的注意事项，请参考 :ref:`更新至一个发布分支` 中的描述。 + +.. _`更新至 master 分支`: + +更新至 master 分支 +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: ESP-IDF 中 master 分支上的代码会时时更新，因此使用 master 分支相当在“流血的边缘试探”，存在一定风险。 + +如需使用 ESP-IDF 的 master 分支，请参考以下步骤： + +- 本地签出至 master 分支:: + + cd $IDF_PATH + git checkout master + git pull + git submodule update --init --recursive + +- 此外，您还应在后续工作中不时使用 ``git pull`` 命令，将远端 master 上的更新同步到本地。注意，在更新 master 分支后，您可能需要更改项代码，也可能遇到新的 bug。 +- 如需从 master 分支切换至一个发布分支或稳定版本，请使用 ``git checkout`` 命令。 + +.. important:: 强烈建议您定期使用 ``git pull`` 和 ``git submodule update --init --recursive`` 命令，确保本地副本的及时更新。旧的 master 分支相当于一个“快照”，可能存在未记录的问题，且无法获得支持。对于半稳定版本，请参考 :ref:`更新至一个发布分支`。 + +.. _`更新至一个发布分支`: + +更新至一个发布分支 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +从稳定性来说，使用“发布分支”相当于在使用 master 分支和稳定版本之间进行折衷，包含一些 master 分支上的新特性，但也同时保证可通过 beta 测试且基本完成了 bug 修复。 + +更多详情，请前往 GitHub 查看完整 `标签列表`_。 + +举例，您可以关注 ESP-IDF v3.1 分支，随时关注该分支上的 bugfix 版本发布（ 例 ``v3.1.1`` 等）:: + + cd $IDF_PATH + git fetch + git checkout release/v3.1 + git pull + git submodule update --init --recursive + +您每次在该分支上使用 ``git pull`` 时都相当于把最新的 bugfix 版本发布更新至您的本地副本中。 + +.. note:: 发布分支并不会有专门的配套文档，建议您使用与本分支最接近的版本。 + +.. _`发布说明页面`: http://github.com/espressif/esp-idf/releases +.. _`分支列表`: https://github.com/espressif/esp-idf/branches +.. _`标签列表`: https://github.com/espressif/esp-idf/tags +.. _`最新稳定版本`: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/