1ESP-IDF Versions 2================ 3 4:link_to_translation:`zh_CN:[中文]` 5 6The ESP-IDF GitHub repository is updated regularly, especially the master branch where new development takes place. 7 8For production use, there are also stable releases available. 9 10 11Releases 12-------- 13 14The documentation for the current stable release version can always be found at this URL: 15 16https://docs.espressif.com/projects/esp-idf/en/stable/ 17 18Documentation for the latest version (master branch) can always be found at this URL: 19 20https://docs.espressif.com/projects/esp-idf/en/latest/ 21 22The full history of releases can be found on the GitHub repository `Releases page`_. There you can find release notes, links to each version of the documentation, and instructions for obtaining each version. 23 24.. only:: html 25 26 Another place to find documentation for all current releases is the documentation page, where you can go to the upper-left corner and click the version dropdown (between the target dropdown and the search bar). You can also use this dropdown to switch between versions of the documentation. 27 28 .. image:: /../_static/choose_version.png 29 30 Documentation for older versions are also still available: 31 32 .. raw:: html 33 :file: ../_static/version_table.html 34 35 36 37Which Version Should I Start With? 38---------------------------------- 39 40- 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`_. 41 42- 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"). 43 44- 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`. 45 46See :ref:`updating` if you already have a local copy of ESP-IDF and wish to update it. 47 48.. _versioning-scheme: 49 50Versioning Scheme 51----------------- 52 53ESP-IDF uses `Semantic Versioning <http://semver.org/>`_. This means that: 54 55- Major Releases, like ``v3.0``, add new functionality and may change functionality. This includes removing deprecated functionality. 56 57 If updating to a new major release (for example, from ``v2.1`` to ``v3.0``), some of your project's code may need updating and functionality may need to be re-tested. The release notes on the `Releases page`_ include lists of Breaking Changes to refer to. 58 59- Minor Releases like ``v3.1`` add new functionality and fix bugs but will not change or remove documented functionality, or make incompatible changes to public APIs. 60 61 If updating to a new minor release (for example, from ``v3.0`` to ``v3.1``), your project's code does not require updating, but you should re-test your project. Pay particular attention to the items mentioned in the release notes on the `Releases page`_. 62 63- Bugfix Releases like ``v3.0.1`` only fix bugs and do not add new functionality. 64 65 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`_. 66 67Support Periods 68--------------- 69 70Each 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. 71 72The `ESP-IDF Support Period Policy`_ explains this in detail, and describes how the support periods for each release are determined. 73 74Each release on the `Releases page`_ includes information about the support period for that particular release. 75 76As a general guideline: 77 78- If starting a new project, use the latest stable release. 79- 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. 80- 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. 81- Always plan to update to a newer release before the release you are using becomes End of Life. 82 83Each ESP-IDF major and minor release (V4.1, V4.2, etc) is supported for 30 months after the initial stable release date. 84 85Supported 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. 86 87Support period is divided into "Service" and "Maintenance" period: 88 89.. list-table:: 90 :header-rows: 1 91 :widths: 25 25 55 92 93 * - Period 94 - Duration 95 - Recommended for new projects? 96 * - Service 97 - 12 months 98 - Yes 99 * - Maintenance 100 - 18 months 101 - No 102 103During the Service period, bugfixes releases are more frequent. In some cases, support for new features may be added during the Service period (this is reserved for features which are needed to meet particular regulatory requirements or standards for new products, and which carry a very low risk of introducing regressions.) 104 105During the Maintenance period, the version is still supported but only bugfixes for high severity issues or security issues will be applied. 106 107Using an “In Service” version is recommended when starting a new project. 108 109Users are encouraged to upgrade all projects 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. 110 111Pre-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. 112 113The 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). 114 115 116.. image:: https://dl.espressif.com/dl/esp-idf/support-periods.svg 117 118 119Checking the Current Version 120---------------------------- 121 122The local ESP-IDF version can be checked by using idf.py:: 123 124 idf.py --version 125 126The 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). 127 128If 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>`. 129 130Examples of ESP-IDF versions: 131 132============================ ===================================================================================== 133Version String Meaning 134============================ ===================================================================================== 135``v3.2-dev-306-gbeb3611ca`` | Master branch pre-release. 136 | - ``v3.2-dev`` - in development for version 3.2. 137 | - ``306`` - number of commits after v3.2 development started. 138 | - ``beb3611ca`` - commit identifier. 139``v3.0.2`` | Stable release, tagged ``v3.0.2``. 140``v3.1-beta1-75-g346d6b0ea`` | Beta version in development (on a :ref:`release branch <updating-release-branch>`). 141 | - ``v3.1-beta1`` - pre-release tag. 142 | - ``75`` - number of commits after the pre-release beta tag was assigned. 143 | - ``346d6b0ea`` - commit identifier. 144``v3.0.1-dirty`` | Stable release, tagged ``v3.0.1``. 145 | - ``dirty`` means that there are modifications in the local ESP-IDF directory. 146============================ ===================================================================================== 147 148 149Git Workflow 150------------ 151 152The development (Git) workflow of the Espressif ESP-IDF team is as follows: 153 154- New work is always added on the master branch (latest version) first. The ESP-IDF version on ``master`` is always tagged with ``-dev`` (for "in development"), for example ``v3.1-dev``. 155- Changes are first added to an internal Git repository for code review and testing but are pushed to GitHub after automated testing passes. 156- When a new version (developed on ``master``) becomes feature complete and "beta" quality, a new branch is made for the release, for example ``release/v3.1``. A pre-release tag is also created, for example ``v3.1-beta1``. You can see a full `list of branches`_ and a `list of tags`_ on GitHub. Beta pre-releases have release notes which may include a significant number of Known Issues. 157- As testing of the beta version progresses, bug fixes will be added to both the ``master`` branch and the release branch. New features for the next release may start being added to ``master`` at the same time. 158- Once testing is nearly complete a new release candidate is tagged on the release branch, for example ``v3.1-rc1``. This is still a pre-release version. 159- If no more significant bugs are found or reported, then the final Major or Minor Version is tagged, for example ``v3.1``. This version appears on the `Releases page`_. 160- As bugs are reported in released versions, the fixes will continue to be committed to the same release branch. 161- Regular bugfix releases are made from the same release branch. After manual testing is complete, a bugfix release is tagged (i.e. ``v3.1.1``) and appears on the `Releases page`_. 162 163 164.. _updating: 165 166Updating ESP-IDF 167---------------- 168 169Updating ESP-IDF depends on which version(s) you wish to follow: 170 171- :ref:`updating-stable-releases` is recommended for production use. 172- :ref:`updating-master` is recommended for the latest features, development use, and testing. 173- :ref:`updating-release-branch` is a compromise between the first two. 174 175.. note:: These guides assume that you already have a local copy of ESP-IDF cloned. To get one, check Step 2 in the :doc:`Getting Started </get-started/index>` guide for any ESP-IDF version. 176 177 178.. _`updating-stable-releases`: 179 180Updating to Stable Release 181^^^^^^^^^^^^^^^^^^^^^^^^^^ 182 183To update to a new ESP-IDF release (recommended for production use), this is the process to follow: 184 185- Check the `Releases page`_ regularly for new releases. 186- When a bugfix release for the version you are using is released (for example, if using ``v3.0.1`` and ``v3.0.2`` is released), check out the new bugfix version into the existing ESP-IDF directory: 187 188.. code-block:: bash 189 190 cd $IDF_PATH 191 git fetch 192 git checkout vX.Y.Z 193 git submodule update --init --recursive 194 195- When major or minor updates are released, check the Release Notes on the releases page and decide if you want to update or to stay with your current release. Updating is via the same Git commands shown above. 196 197.. note:: If you installed the stable release via zip file instead of using git, it might not be possible to update versions using the commands. In this case, update by downloading a new zip file and replacing the entire ``IDF_PATH`` directory with its contents. 198 199 200.. _`updating-pre-release`: 201 202Updating to a Pre-Release Version 203^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 204 205It is also possible to ``git checkout`` a tag corresponding to a pre-release version or release candidate, the process is the same as :ref:`updating-stable-releases`. 206 207Pre-release tags are not always found on the `Releases page`_. Consult the `list of tags`_ on GitHub for a full list. Caveats for using a pre-release are similar to :ref:`updating-release-branch`. 208 209.. _`updating-master`: 210 211Updating to Master Branch 212^^^^^^^^^^^^^^^^^^^^^^^^^ 213 214.. note:: Using Master branch means living "on the bleeding edge" with the latest ESP-IDF code. 215 216To use the latest version on the ESP-IDF master branch, this is the process to follow: 217 218- Check out the master branch locally:: 219 220 cd $IDF_PATH 221 git checkout master 222 git pull 223 git submodule update --init --recursive 224 225- Periodically, re-run ``git pull`` to pull the latest version of master. Note that you may need to change your project or report bugs after updating your master branch. 226- To switch from master to a release branch or stable version, run ``git checkout`` as shown in the other sections. 227 228.. important:: It is strongly recommended to regularly run ``git pull`` and then ``git submodule update --init --recursive`` so a local copy of master does not get too old. Arbitrary old master branch revisions are effectively unsupportable "snapshots" that may have undocumented bugs. For a semi-stable version, try :ref:`updating-release-branch` instead. 229 230.. _`updating-release-branch`: 231 232Updating to a Release Branch 233^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 234 235In terms of stability, using a release branch is part-way between using the master branch and only using stable releases. A release branch is always beta quality or better, and receives bug fixes before they appear in each stable release. 236 237You can find a `list of branches`_ on GitHub. 238 239For example, to follow the branch for ESP-IDF v3.1, including any bugfixes for future releases like ``v3.1.1``, etc:: 240 241 cd $IDF_PATH 242 git fetch 243 git checkout release/v3.1 244 git pull 245 git submodule update --init --recursive 246 247Each time you ``git pull`` this branch, ESP-IDF will be updated with fixes for this release. 248 249.. note:: There is no dedicated documentation for release branches. It is recommended to use the documentation for the closest version to the branch which is currently checked out. 250 251.. _`Releases page`: http://github.com/espressif/esp-idf/releases 252.. _`list of branches`: https://github.com/espressif/esp-idf/branches 253.. _`list of tags`: https://github.com/espressif/esp-idf/tags 254.. _`current stable version`: https://docs.espressif.com/projects/esp-idf/en/stable/ 255.. _`ESP-IDF Support Period Policy`: https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY.md 256
