install report: add version field

Also, affirm the experimental status of the feature.

Author: sbidoul

docs/html/reference/installation-report.md

@@ -7,6 +7,14 @@ it did install (or what it would have installed, if used with the `--dry-run` op
 
 The report is a JSON object with the following properties:
 
+- `version`: the string `0`, denoting that the installation report is an experimental
+  feature. This value will change to `1` in pip 22.3 or 23.0 when the feature is deemed
+  stable after gathering user feedback. Backward incompatible changes may be introduced
+  in version `1` without notice. After that, it will change only if and when backward
+  incompatible changes are introduced, such as removing mandatory fields or changing the
+  semantics or data type of existing fields. The introduction of backward incompatible
+  changes will follow the usual pip processes such as the deprecation cycle or feature
+  flags. Tools must check this field to ensure they support the corresponding version.
 - `pip_version`: a string with the version of pip used to produce the report.
 - `install`: an object where the properties are the canonicalized names of the
   distribution packages (to be) installed and the values are of type
@@ -52,6 +60,7 @@ will produce an output similar to this (metadata abriged for clarity):
 
 ```json
 {
+  "version": "0",
   "pip_version": "22.2",
   "install": {
     "pydantic": {

news/53.feature.rst

@@ -1,3 +1,3 @@
-Add ``--report`` to the install command to generate a json report of what was installed.
-In combination with ``--dry-run`` and ``--ignore-installed`` it can be used to resolve
-the requirements.
+Add an experimental ``--report`` option to the install command to generate a json report
+of what was installed. In combination with ``--dry-run`` and ``--ignore-installed`` it
+can be used to resolve the requirements.

src/pip/_internal/models/installation_report.py

@@ -39,6 +39,7 @@ def _install_req_to_dict(cls, ireq: InstallRequirement) -> Dict[str, Any]:
 
     def to_dict(self) -> Dict[str, Any]:
         return {
+            "version": "0",
             "pip_version": __version__,
             "install": {
                 canonicalize_name(ireq.metadata["Name"]): self._install_req_to_dict(