Design proposal for supported image formats (v3)

In this version we added explanation about how to choose the format when the
VDI is created but also the destination format during migration. We also fix
some typos.

Signed-off-by: Guillaume <guillaume.thouvenin@vates.tech>

Author: gthvn1

doc/content/design/sm-supported-image-formats.md

@@ -2,7 +2,7 @@
 title: Add supported image formats in sm-list
 layout: default
 design_doc: true
-revision: 2
+revision: 3
 status: proposed
 ---
 
@@ -22,32 +22,40 @@ available formats.
 # Design Proposal
 
 To expose the available image formats to clients (e.g., XenCenter, XenOrchestra, etc.),
-we propose adding a new field called `supported-image-formats` to the Storage Manager (SM)
-module. This field will be included in the output of the `SM.get_all_records` call.
+we propose adding a new field called `supported_image_formats` to the Storage Manager
+(SM) module. This field will be included in the output of the `SM.get_all_records` call.
 
-The `supported-image-formats` field will be populated by retrieving information
+The `supported_image_formats` field will be populated by retrieving information
 from the SMAPI drivers. Specifically, each driver will update its `DRIVER_INFO`
 dictionary with a new key, `supported_image_formats`, which will contain a list
 of strings representing the supported image formats
 (for example: `["vhd", "raw", "qcow2"]`).
 
-The list designates the driver's preferred VDI format as its first entry. That
-means that when migrating a VDI, the destination storage repository will
-attempt to create a VDI in this preferred format. If the default format cannot
-be used (e.g., due to size limitations), an error will be generated.
+When creating new VDI, you can choose the format by passing the option
+`type=qcow2` to the `sm_config` parameter. If no format is specified, it is
+up to the driver to choose its preferred format.
+
+During the migration of a VDI, since an SR can now support different types of
+storage, we need a way to specify which format should be used. To achieve this,
+we propose adding a preferred image format for a given SR. When the SR is created,
+based on the list retrieved using `supported_image_formats` from the SM, we can
+pass `preferred-image-format=qcow2` to the `sm_config` parameter of the SR. If no
+format is specified, it is up to the driver to choose its preferred format. If the
+default format cannot be used (e.g., due to size limitations), an error will be
+generated.
 
 If a driver does not provide this information (as is currently the case with existing
 drivers), the default value will be an empty array. This signifies that it is the
-driver that decides which format it will use. This ensures that the modification
-remains compatible with both current and future drivers.
+driver that decides which format it will use to create or migrate a VDI. This ensures
+that the modification remains compatible with both current and future drivers.
 
 With this new information, listing all parameters of the SM object will return:
 
 ```bash
 # xe sm-list params=all
 ```
 
-will output something like:
+will output something like (notice that CLI uses hyphens):
 
 ```
 uuid ( RO)                         : c6ae9a43-fff6-e482-42a9-8c3f8c533e36
@@ -70,7 +78,7 @@ be incremented.
 
 # Impact
 
-- **Data Model:** A new field (`supported-image-formats`) is added to the SM records.
+- **Data Model:** A new field (`supported_image_formats`) is added to the SM records.
 - **Client Awareness:** Clients like the `xe` CLI will now be able to query and display the supported image formats for a given SR.
 - **Database Versioning:** The XAPI database version will be updated to reflect this change.