docs: Semantic versioning

Author: radimkarnis

docs/en/index.rst

@@ -50,4 +50,5 @@ More Information
    Advanced Topics <advanced-topics/index>
    Troubleshooting <troubleshooting>
    Contribute <contributing>
+   Versions <versions>
    About <about>

docs/en/versions.rst

@@ -0,0 +1,48 @@
+.. _versions:
+
+Versions
+========
+
+Starting from ``v4.0.0``, ``esptool.py`` adopts the `semantic versioning specification <https://semver.org/>`_, following the ``MAJOR.MINOR.PATCH`` version number.
+
+Major release ``v4`` is under active development, receiving new features and bugfixes, while ``v3`` only keeps receiving important bugfixes.
+
+There are no support periods defined and bugfixes are not planned, therefore it is strongly recommended to install the latest version possible.
+
+.. note::
+
+    The following information is directed mainly towards package maintainers. Regular users should always use the most recent version of ``esptool.py`` to benefit from the latest features and bugfixes.
+
+Use the latest esptool (recommended)
+------------------------------------
+
+If your use case doesn't impose any constraints on ``esptool.py``, the latest release should be always used.
+To see the latest available version and its release notes, visit the `release page on GitHub <https://github.com/espressif/esptool/releases>`_.
+
+To get the latest possible version, simply define your dependency as ``esptool`` (without any release operator and a version identifier).
+
+Use the latest bugfix release of a minor esptool release
+--------------------------------------------------------
+
+Some use cases might require a specific ``esptool.py`` version without getting new features, but with automatic bugfixes.
+
+This can be achieved by defining your dependency as ``esptool~=4.0.1`` (explicitly stating the ``MAJOR``, ``MINOR``, and ``PATCH`` numbers).
+This notation selects the latest version of ``esptool.py``, greater than or equal to ``v4.0.1``, but still in the ``v4.0.*`` version (this compatible release clause is approximately equivalent to the pair of comparison clauses ``>= 4.0.1``, ``== 4.0.*``).
+So, for example, ``v4.1.0`` won't be downloaded. More information about compatible release clauses `can be found here <https://peps.python.org/pep-0440/#compatible-release>`_.
+
+Use the latest esptool without any future breaking change
+---------------------------------------------------------
+
+If you also want to get new features (instead of just bugfixes), define your version requirement as ``esptool~=4.0`` (explicitly stating only the ``MAJOR`` and ``MINOR`` numbers). This way the latest minor versions (``>= 4.0``, ``== 4.*``) are automatically installed.
+Backward-compatibility is still ensured, because ``esptool.py`` respects the semantic versioning specification (which states that breaking changes should occur only in ``MAJOR`` versions).
+
+Use the previous major esptool release (only if you cannot upgrade)
+-------------------------------------------------------------------
+
+If your use case is not compatible with the latest ``MAJOR`` release of ``esptool.py``, a previous compatible version has to be specified.
+This can be achieved by defining your dependency as ``esptool~=3.0`` (explicitly stating your desired ``MAJOR`` number and at least also the ``MINOR`` number, ``PATCH`` can also be specified).
+
+Use a specific esptool release
+------------------------------
+
+If a very specific release is required, define your dependency as ``esptool==4.1.2``. This specific version will be used and no new features or bugfixes will be automatically installed.