doc: state PackageId/SourceId string is opaque

Cargo tries to maintain the stability of every output it emits.
However, for things like `PackageId` and `SourceId` users should
see them as opaque strings. We generally don't change it but we
want to reserve the right to change when it is required.

src/doc/man/cargo-metadata.md

@@ -13,15 +13,34 @@ cargo-metadata --- Machine-readable metadata about the current package
 Output JSON to stdout containing information about the workspace members and
 resolved dependencies of the current package.
 
-It is recommended to include the `--format-version` flag to future-proof
-your code to ensure the output is in the format you are expecting.
+The format of the output is subject to change in futures versions of Cargo. It
+is recommended to include the `--format-version` flag to future-proof your code
+to ensure the output is in the format you are expecting. For more on the
+expectations, see ["Compatibility"](#compatibility).
 
 See the [cargo_metadata crate](https://crates.io/crates/cargo_metadata)
 for a Rust API for reading the metadata.
 
 ## OUTPUT FORMAT
 
-The output has the following format:
+### Compatibility
+
+Within the same output format version, the compatibility is maintained, except
+some scenarios. The following is a non-exhaustive list of changes that are not
+considersed as incompatibile:
+
+* **Adding new fields** — New fields will be added when needed. Reserving this
+  helps Cargo evolve without bumping the format version too often.
+* **Adding new values for enum-like fields** — Same as adding new fields. It
+  keeps metadata evolving without stagnation.
+* **Changing opaque representations** — The inner representations of some
+  fields are implementation details. For example, fields related to "Package ID"
+  or "Source ID" are treated as opaque identifiers to differentiate packages or
+  sources. Consumers shouldn't rely on those representations unless specified.
+
+### JSON format
+
+The JSON output has the following format:
 
 ```javascript
 {
@@ -34,22 +53,35 @@ The output has the following format:
             "name": "my-package",
             /* The version of the package. */
             "version": "0.1.0",
-            /* The Package ID, a unique identifier for referring to the package. */
+            /* The Package ID, an opaque and unique identifier for referring to the
+               package. See "Compatibility" above for the stability guarantee.
+            */
             "id": "my-package 0.1.0 (path+file:///path/to/my-package)",
             /* The license value from the manifest, or null. */
             "license": "MIT/Apache-2.0",
             /* The license-file value from the manifest, or null. */
             "license_file": "LICENSE",
             /* The description value from the manifest, or null. */
             "description": "Package description.",
-            /* The source ID of the package. This represents where
-               a package is retrieved from.
+            /* The source ID of the package, an "opaque" identifier representing
+               where a package is retrieved from. See "Compatibility" above for
+               the stability guarantee.
+
                This is null for path dependencies and workspace members.
+
                For other dependencies, it is a string with the format:
                - "registry+URL" for registry-based dependencies.
                  Example: "registry+https://github.com/rust-lang/crates.io-index"
                - "git+URL" for git-based dependencies.
                  Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
+               - "sparse+URL" for dependencies from a sparse registry
+                 Example: "sparse+https://my-sparse-registry.org"
+
+               The value after the `+` is not explicitly defined, and may change
+               between versions of Cargo and may not directly correlate to other
+               things, such as registry definitions in a config file. New source
+               kinds may be added in the future which will have different `+`
+               prefixed identifiers.
             */
             "source": null,
             /* Array of dependencies declared in the package's manifest. */

src/doc/man/generated_txt/cargo-metadata.txt

@@ -10,14 +10,34 @@ DESCRIPTION
        Output JSON to stdout containing information about the workspace members
        and resolved dependencies of the current package.
 
-       It is recommended to include the --format-version flag to future-proof
-       your code to ensure the output is in the format you are expecting.
+       The format of the output is subject to change in futures versions of
+       Cargo. It is recommended to include the --format-version flag to
+       future-proof your code to ensure the output is in the format you are
+       expecting. For more on the expectations, see “Compatibility”.
 
        See the cargo_metadata crate <https://crates.io/crates/cargo_metadata>
        for a Rust API for reading the metadata.
 
 OUTPUT FORMAT
-       The output has the following format:
+   Compatibility
+       Within the same output format version, the compatibility is maintained,
+       except some scenarios. The following is a non-exhaustive list of changes
+       that are not considersed as incompatibile:
+
+       o  Adding new fields — New fields will be added when needed. Reserving
+          this helps Cargo evolve without bumping the format version too often.
+
+       o  Adding new values for enum-like fields — Same as adding new fields.
+          It keeps metadata evolving without stagnation.
+
+       o  Changing opaque representations — The inner representations of some
+          fields are implementation details. For example, fields related to
+          “Package ID” or “Source ID” are treated as opaque identifiers
+          to differentiate packages or sources. Consumers shouldn’t rely on
+          those representations unless specified.
+
+   JSON format
+       The JSON output has the following format:
 
            {
                /* Array of all packages in the workspace.
@@ -29,22 +49,35 @@ OUTPUT FORMAT
                        "name": "my-package",
                        /* The version of the package. */
                        "version": "0.1.0",
-                       /* The Package ID, a unique identifier for referring to the package. */
+                       /* The Package ID, an opaque and unique identifier for referring to the
+                          package. See "Compatibility" above for the stability guarantee.
+                       */
                        "id": "my-package 0.1.0 (path+file:///path/to/my-package)",
                        /* The license value from the manifest, or null. */
                        "license": "MIT/Apache-2.0",
                        /* The license-file value from the manifest, or null. */
                        "license_file": "LICENSE",
                        /* The description value from the manifest, or null. */
                        "description": "Package description.",
-                       /* The source ID of the package. This represents where
-                          a package is retrieved from.
+                       /* The source ID of the package, an "opaque" identifier representing
+                          where a package is retrieved from. See "Compatibility" above for
+                          the stability guarantee.
+
                           This is null for path dependencies and workspace members.
+
                           For other dependencies, it is a string with the format:
                           - "registry+URL" for registry-based dependencies.
                             Example: "registry+https://github.com/rust-lang/crates.io-index"
                           - "git+URL" for git-based dependencies.
                             Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
+                          - "sparse+URL" for dependencies from a sparse registry
+                            Example: "sparse+https://my-sparse-registry.org"
+
+                          The value after the `+` is not explicitly defined, and may change
+                          between versions of Cargo and may not directly correlate to other
+                          things, such as registry definitions in a config file. New source
+                          kinds may be added in the future which will have different `+`
+                          prefixed identifiers.
                        */
                        "source": null,
                        /* Array of dependencies declared in the package's manifest. */

src/doc/src/commands/cargo-metadata.md

@@ -13,15 +13,34 @@ cargo-metadata --- Machine-readable metadata about the current package
 Output JSON to stdout containing information about the workspace members and
 resolved dependencies of the current package.
 
-It is recommended to include the `--format-version` flag to future-proof
-your code to ensure the output is in the format you are expecting.
+The format of the output is subject to change in futures versions of Cargo. It
+is recommended to include the `--format-version` flag to future-proof your code
+to ensure the output is in the format you are expecting. For more on the
+expectations, see ["Compatibility"](#compatibility).
 
 See the [cargo_metadata crate](https://crates.io/crates/cargo_metadata)
 for a Rust API for reading the metadata.
 
 ## OUTPUT FORMAT
 
-The output has the following format:
+### Compatibility
+
+Within the same output format version, the compatibility is maintained, except
+some scenarios. The following is a non-exhaustive list of changes that are not
+considersed as incompatibile:
+
+* **Adding new fields** — New fields will be added when needed. Reserving this
+  helps Cargo evolve without bumping the format version too often.
+* **Adding new values for enum-like fields** — Same as adding new fields. It
+  keeps metadata evolving without stagnation.
+* **Changing opaque representations** — The inner representations of some
+  fields are implementation details. For example, fields related to "Package ID"
+  or "Source ID" are treated as opaque identifiers to differentiate packages or
+  sources. Consumers shouldn't rely on those representations unless specified.
+
+### JSON format
+
+The JSON output has the following format:
 
 ```javascript
 {
@@ -34,22 +53,35 @@ The output has the following format:
             "name": "my-package",
             /* The version of the package. */
             "version": "0.1.0",
-            /* The Package ID, a unique identifier for referring to the package. */
+            /* The Package ID, an opaque and unique identifier for referring to the
+               package. See "Compatibility" above for the stability guarantee.
+            */
             "id": "my-package 0.1.0 (path+file:///path/to/my-package)",
             /* The license value from the manifest, or null. */
             "license": "MIT/Apache-2.0",
             /* The license-file value from the manifest, or null. */
             "license_file": "LICENSE",
             /* The description value from the manifest, or null. */
             "description": "Package description.",
-            /* The source ID of the package. This represents where
-               a package is retrieved from.
+            /* The source ID of the package, an "opaque" identifier representing
+               where a package is retrieved from. See "Compatibility" above for
+               the stability guarantee.
+
                This is null for path dependencies and workspace members.
+
                For other dependencies, it is a string with the format:
                - "registry+URL" for registry-based dependencies.
                  Example: "registry+https://github.com/rust-lang/crates.io-index"
                - "git+URL" for git-based dependencies.
                  Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
+               - "sparse+URL" for dependencies from a sparse registry
+                 Example: "sparse+https://my-sparse-registry.org"
+
+               The value after the `+` is not explicitly defined, and may change
+               between versions of Cargo and may not directly correlate to other
+               things, such as registry definitions in a config file. New source
+               kinds may be added in the future which will have different `+`
+               prefixed identifiers.
             */
             "source": null,
             /* Array of dependencies declared in the package's manifest. */

src/etc/man/cargo-metadata.1

@@ -11,13 +11,37 @@ cargo\-metadata \[em] Machine\-readable metadata about the current package
 Output JSON to stdout containing information about the workspace members and
 resolved dependencies of the current package.
 .sp
-It is recommended to include the \fB\-\-format\-version\fR flag to future\-proof
-your code to ensure the output is in the format you are expecting.
+The format of the output is subject to change in futures versions of Cargo. It
+is recommended to include the \fB\-\-format\-version\fR flag to future\-proof your code
+to ensure the output is in the format you are expecting. For more on the
+expectations, see \[lq]Compatibility\[rq]\&.
 .sp
 See the \fIcargo_metadata crate\fR <https://crates.io/crates/cargo_metadata>
 for a Rust API for reading the metadata.
 .SH "OUTPUT FORMAT"
-The output has the following format:
+.SS "Compatibility"
+Within the same output format version, the compatibility is maintained, except
+some scenarios. The following is a non\-exhaustive list of changes that are not
+considersed as incompatibile:
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'\fBAdding new fields\fR \[em] New fields will be added when needed. Reserving this
+helps Cargo evolve without bumping the format version too often.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'\fBAdding new values for enum\-like fields\fR \[em] Same as adding new fields. It
+keeps metadata evolving without stagnation.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'\fBChanging opaque representations\fR \[em] The inner representations of some
+fields are implementation details. For example, fields related to \[lq]Package ID\[rq]
+or \[lq]Source ID\[rq] are treated as opaque identifiers to differentiate packages or
+sources. Consumers shouldn\[cq]t rely on those representations unless specified.
+.RE
+.SS "JSON format"
+The JSON output has the following format:
 .sp
 .RS 4
 .nf
@@ -31,22 +55,35 @@ The output has the following format:
             "name": "my\-package",
             /* The version of the package. */
             "version": "0.1.0",
-            /* The Package ID, a unique identifier for referring to the package. */
+            /* The Package ID, an opaque and unique identifier for referring to the
+               package. See "Compatibility" above for the stability guarantee.
+            */
             "id": "my\-package 0.1.0 (path+file:///path/to/my\-package)",
             /* The license value from the manifest, or null. */
             "license": "MIT/Apache\-2.0",
             /* The license\-file value from the manifest, or null. */
             "license_file": "LICENSE",
             /* The description value from the manifest, or null. */
             "description": "Package description.",
-            /* The source ID of the package. This represents where
-               a package is retrieved from.
+            /* The source ID of the package, an "opaque" identifier representing
+               where a package is retrieved from. See "Compatibility" above for
+               the stability guarantee.
+
                This is null for path dependencies and workspace members.
+
                For other dependencies, it is a string with the format:
                \- "registry+URL" for registry\-based dependencies.
                  Example: "registry+https://github.com/rust\-lang/crates.io\-index"
                \- "git+URL" for git\-based dependencies.
                  Example: "git+https://github.com/rust\-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
+               \- "sparse+URL" for dependencies from a sparse registry
+                 Example: "sparse+https://my\-sparse\-registry.org"
+
+               The value after the `+` is not explicitly defined, and may change
+               between versions of Cargo and may not directly correlate to other
+               things, such as registry definitions in a config file. New source
+               kinds may be added in the future which will have different `+`
+               prefixed identifiers.
             */
             "source": null,
             /* Array of dependencies declared in the package's manifest. */