feat(image_info): Deprecate the --version 1 output format

BREAKING CHANGE

Author: radimkarnis

docs/en/advanced-topics/firmware-image-format.rst

@@ -189,4 +189,4 @@ The file is padded with zeros until its size is one byte less than a multiple of
 Analyzing a Binary Image
 ------------------------
 
-To analyze a binary image and get a complete summary of its headers and segments, use the :ref:`image_info <image-info>` command with the ``--version 2`` option.
+To analyze a binary image and get a complete summary of its headers and segments, use the :ref:`image_info <image-info>` command.

docs/en/esptool/basic-commands.rst

@@ -225,15 +225,13 @@ By default, ``elf2image`` uses the sections in the ELF file to generate each seg
 Output .bin Image Details: image_info
 -------------------------------------
 
-The ``image_info`` command outputs some information (load addresses, sizes, etc) about a ``.bin`` file created by ``elf2image``. Command also supports ``.hex`` file created by ``merge_bin`` command from supported ``.bin`` files.
-
-To view more information about the image, such as set flash size, frequency and mode, or extended header information, use the ``--version 2`` option. This extended output will become the default in a future major release.
+The ``image_info`` command outputs some information (load addresses, segment sizes, set flash size, frequency, and mode, extended header information, etc) about a ``.bin`` file created by ``elf2image``. Command also supports ``.hex`` file created by ``merge_bin`` command from supported ``.bin`` files.
 
 This information corresponds to the headers described in :ref:`image-format`.
 
 ::
 
-    esptool.py image_info --version 2 my_esp_app.bin
+    esptool.py image_info my_esp_app.bin
 
 .. only:: not esp8266
 

docs/en/index.rst

@@ -51,5 +51,6 @@ More Information
    Troubleshooting <troubleshooting>
    Contribute <contributing>
    Versions <versions>
+   Migration Guide <migration-guide>
    Resources <resources>
    About <about>

docs/en/migration-guide.rst

@@ -0,0 +1,23 @@
+.. _migration:
+
+esptool.py ``v5`` Migration Guide
+=================================
+
+This document describes the breaking changes made to esptool.py in the major release ``v5``. It provides guidance on adapting existing workflows and scripts to ensure compatibility when updating from ``v4.*``.
+
+
+``image_info`` Output Format Change
+***********************************
+
+The output format of the :ref:`image_info <image-info>` command has been **updated in v5**. The original format (``--version 1``) is **deprecated** and replaced by the updated format (``--version 2``). The ``--version`` argument has been **removed entirely**, and the new format is now the default and only option.
+
+**Changes in the New Format:**
+
+- Improved readability and structure
+- Additional metadata fields for better debugging and analysis
+- Consistent formatting for all ESP chip variants
+
+**Migration Steps:**
+
+1. Update any scripts or tools that parse the ``image_info`` output to use the new format
+2. Remove any ``--version`` arguments from ``image_info`` commands

esptool/__init__.py

@@ -402,13 +402,6 @@ def add_spi_flash_subparsers(
     parser_image_info.add_argument(
         "filename", help="Image file to parse", action=AutoHex2BinAction
     )
-    parser_image_info.add_argument(
-        "--version",
-        "-v",
-        help="Output format version (1 - legacy, 2 - extended)",
-        choices=["1", "2"],
-        default="1",
-    )
 
     parser_make_image = subparsers.add_parser(
         "make_image", help="Create an application image from binary files"