Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
OVMS3-idf/docs/en/versions.rst

193 lines
11 KiB
ReStructuredText
Raw Normal View History

docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
ESP-IDF Versions
================
Add translation for version file
2019-05-10 11:17:49 +00:00
:link_to_translation:`zh_CN:[中文]`
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
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.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
Releases
--------
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
The documentation for the current stable release version can always be found at this URL:
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
https://docs.espressif.com/projects/esp-idf/en/stable/
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
Documentation for the latest version (master branch) can always be found at this URL:
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
https://docs.espressif.com/projects/esp-idf/en/latest/
The 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.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
Another place to find documentation for all releases is the documentation page, where you can go to the bottom-left corner and click the versions dropup (a bar with a small triangle). You can also use this dropup to switch between versions of the documentation.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
.. image:: /../_static/choose_version.png
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
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).
- 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").
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
- 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`.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
See :ref:`updating` if you already have a local copy of ESP-IDF and wish to update it.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
Versioning Scheme
-----------------
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
ESP-IDF uses `Semantic Versioning <http://semver.org/>`_. This means that:
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
- Major Releases, like ``v3.0``, add new functionality and may change functionality. This includes removing deprecated functionality.
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.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
- 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.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
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`_.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
- Bugfix Releases like ``v3.0.1`` only fix bugs and do not add new functionality.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
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`_.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
Checking the Current Version
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
----------------------------
Add idf.py --version option Update docs on how to check IDF version Show dependencies check information only in verbose mode
2019-08-15 13:42:15 +00:00
The local ESP-IDF version can be checked by using idf.py::
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
Add idf.py --version option Update docs on how to check IDF version Show dependencies check information only in verbose mode
2019-08-15 13:42:15 +00:00
idf.py --version
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
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).
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
Examples of ESP-IDF versions:
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
============================ =====================================================================================
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
Version String Meaning
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
============================ =====================================================================================
``v3.2-dev-306-gbeb3611ca`` | Master branch pre-release.
| - ``v3.2-dev`` - in development for version 3.2.
| - ``306`` - number of commits after v3.2 development started.
| - ``beb3611ca`` - commit identifier.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
``v3.0.2`` Stable release, tagged ``v3.0.2``.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
``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.
| - ``346d6b0ea`` - commit identifier.
``v3.0.1-dirty`` | Stable release, tagged ``v3.0.1``.
| - ``dirty`` means that there are modifications in the local ESP-IDF directory.
============================ =====================================================================================
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
Git Workflow
------------
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
The development (Git) workflow of the Espressif ESP-IDF team is as follows:
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
- 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``.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
- Changes are first added to an internal Git repository for code review and testing but are pushed to GitHub after automated testing passes.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
- 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.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
- 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.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
- 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.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
- 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`_.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
- As bugs are reported in released versions, the fixes will continue to be committed to the same release branch.
- 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`_.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
.. _updating:
Updating ESP-IDF
----------------
Updating ESP-IDF depends on which version(s) you wish to follow:
- :ref:`updating-stable-releases` is recommended for production use.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
- :ref:`updating-master` is recommended for the latest features, development use, and testing.
- :ref:`updating-release-branch` is a compromise between the first two.
.. 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.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
.. _`updating-stable-releases`:
Updating to Stable Release
^^^^^^^^^^^^^^^^^^^^^^^^^^
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
To update to a new ESP-IDF release (recommended for production use), this is the process to follow:
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
- Check the `Releases page`_ regularly for new releases.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
- 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:
.. code-block:: bash
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
cd $IDF_PATH
git fetch
git checkout vX.Y.Z
git submodule update --init --recursive
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
- 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.
.. 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.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
.. _`updating-pre-release`:
Updating to a Pre-Release Version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It 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`.
Pre-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`.
.. _`updating-master`:
Updating to Master Branch
^^^^^^^^^^^^^^^^^^^^^^^^^
.. note:: Using Master branch means living "on the bleeding edge" with the latest ESP-IDF code.
To use the latest version on the ESP-IDF master branch, this is the process to follow:
- Check out the master branch locally::
cd $IDF_PATH
git checkout master
git pull
git submodule update --init --recursive
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
- 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.
- To switch from master to a release branch or stable version, run ``git checkout`` as shown in the other sections.
.. 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.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
.. _`updating-release-branch`:
Updating to a Release Branch
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
In 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.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
You can find a `list of branches`_ on GitHub.
For example, to follow the branch for ESP-IDF v3.1, including any bugfixes for future releases like ``v3.1.1``, etc::
cd $IDF_PATH
git fetch
git checkout release/v3.1
git pull
docs: fix git submodule update command Closes https://github.com/espressif/esp-idf/issues/2584
2018-10-22 05:33:26 +00:00
git submodule update --init --recursive
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
Each time you ``git pull`` this branch, ESP-IDF will be updated with fixes for this release.
Review the versions.rst document.
2019-04-12 06:59:26 +00:00
.. 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.
docs: Add version-specific include files, version documentation * "git clone" command and a small version header are generated depending on git properties. * Add Versions page with details about each version * Make it clear using master branch is living on the "bleeding edge"
2018-07-25 04:30:15 +00:00
.. _`Releases page`: http://github.com/espressif/esp-idf/releases
.. _`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/
Reference in a new issue Copy permalink