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.
rust-lang · Jun 27, 2023 · c5729c6 · c5729c6
1 parent 5febbe5
commit c5729c6
Show file tree

Hide file tree

Showing 4 changed files with 56 additions and 36 deletions.
diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md
@@ -34,22 +34,27 @@ 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, a unique identifier for referring to the package.
+
+               There is no stability guarantee of the format between versions
+               of Cargo. It should generally be treated as an opaque string.
+            */
             "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.
-               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"
+            /* The source ID of the package. This represents where a package is
+               retrieved from.
+
+               This is "null" for path dependencies and workspace members.
+
+               There is no stability guarantee of the format between versions
+               of Cargo. The entire source string should generally be treated
+               as an opaque string to differentiate packages (such as those
+               with the same name, but coming from different sources).
             */
             "source": null,
             /* Array of dependencies declared in the package's manifest. */

diff --git a/src/doc/man/generated_txt/cargo-metadata.txt b/src/doc/man/generated_txt/cargo-metadata.txt
@@ -29,22 +29,27 @@ 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, a unique identifier for referring to the package.
+
+                          There is no stability guarantee of the format between versions
+                          of Cargo. It should generally be treated as an opaque string.
+                       */
                        "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.
-                          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"
+                       /* The source ID of the package. This represents where a package is
+                          retrieved from.
+
+                          This is "null" for path dependencies and workspace members.
+
+                          There is no stability guarantee of the format between versions
+                          of Cargo. The entire source string should generally be treated
+                          as an opaque string to differentiate packages (such as those
+                          with the same name, but coming from different sources).
                        */
                        "source": null,
                        /* Array of dependencies declared in the package's manifest. */

diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md
@@ -34,22 +34,27 @@ 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, a unique identifier for referring to the package.
+
+               There is no stability guarantee of the format between versions
+               of Cargo. It should generally be treated as an opaque string.
+            */
             "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.
-               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"
+            /* The source ID of the package. This represents where a package is
+               retrieved from.
+
+               This is "null" for path dependencies and workspace members.
+
+               There is no stability guarantee of the format between versions
+               of Cargo. The entire source string should generally be treated
+               as an opaque string to differentiate packages (such as those
+               with the same name, but coming from different sources).
             */
             "source": null,
             /* Array of dependencies declared in the package's manifest. */

diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1
@@ -31,22 +31,27 @@ 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, a unique identifier for referring to the package.
+
+               There is no stability guarantee of the format between versions
+               of Cargo. It should generally be treated as an opaque string.
+            */
             "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.
-               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"
+            /* The source ID of the package. This represents where a package is
+               retrieved from.
+
+               This is "null" for path dependencies and workspace members.
+
+               There is no stability guarantee of the format between versions
+               of Cargo. The entire source string should generally be treated
+               as an opaque string to differentiate packages (such as those
+               with the same name, but coming from different sources).
             */
             "source": null,
             /* Array of dependencies declared in the package's manifest. */