docs(metadata): Stabilize id format as PackageIDSpec

This makes it so you can take a package from `cargo metadata` and then pass it with the `--package` option without worrying about ambiguity. Fixes #7267
rust-lang · Dec 6, 2023 · 111f0d0 · 111f0d0
1 parent cad105a
commit 111f0d0
Show file tree

Hide file tree

Showing 4 changed files with 37 additions and 15 deletions.
diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md
@@ -34,8 34,8 @@ considersed as incompatible:
 * **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
  fields are implementation details. For example, fields related to
  "Source ID" are treated as opaque identifiers to differentiate packages or
  sources. Consumers shouldn't rely on those representations unless specified.
 
 ### JSON format
@@ -53,8 53,8 @@ The JSON output has the following format:
  "name": "my-package",
  /* The version of the package. */
  "version": "0.1.0",
- /* The Package ID, an opaque and unique identifier for referring to the
- package. See "Compatibility" above for the stability guarantee.
  /* The Package ID for referring to the
  package within the document and as the `--package` argument to many commands
  */
  "id": "file:///path/to/my-package#0.1.0",
  /* The license value from the manifest, or null. */
@@ -331,6 331,11 @@ The JSON output has the following format:
 }
 ````
 
 Notes:
 - For `"id"` field syntax, see [Package ID Specifications] in the reference.
 
 [Package ID Specifications]: ../reference/pkgid-spec.html
 
 ## OPTIONS
 
 ### Output Options

diff --git a/src/doc/man/generated_txt/cargo-metadata.txt b/src/doc/man/generated_txt/cargo-metadata.txt
@@ -32,9 32,9 @@ OUTPUT FORMAT
 
  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.
  “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:
@@ -49,8 49,8 @@ OUTPUT FORMAT
  "name": "my-package",
  /* The version of the package. */
  "version": "0.1.0",
- /* The Package ID, an opaque and unique identifier for referring to the
- package. See "Compatibility" above for the stability guarantee.
  /* The Package ID for referring to the
  package within the document and as the `--package` argument to many commands
  */
  "id": "file:///path/to/my-package#0.1.0",
  /* The license value from the manifest, or null. */
@@ -326,6 326,12 @@ OUTPUT FORMAT
  }
  }
 
  Notes:
 
  o For "id" field syntax, see Package ID Specifications
  <https://doc.rust-lang.org/cargo/reference/pkgid-spec.html> in the
  reference.
 
 OPTIONS
  Output Options
  --no-deps

diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md
@@ -34,8 34,8 @@ considersed as incompatible:
 * **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
  fields are implementation details. For example, fields related to
  "Source ID" are treated as opaque identifiers to differentiate packages or
  sources. Consumers shouldn't rely on those representations unless specified.
 
 ### JSON format
@@ -53,8 53,8 @@ The JSON output has the following format:
  "name": "my-package",
  /* The version of the package. */
  "version": "0.1.0",
- /* The Package ID, an opaque and unique identifier for referring to the
- package. See "Compatibility" above for the stability guarantee.
  /* The Package ID for referring to the
  package within the document and as the `--package` argument to many commands
  */
  "id": "file:///path/to/my-package#0.1.0",
  /* The license value from the manifest, or null. */
@@ -331,6 331,11 @@ The JSON output has the following format:
 }
 ````
 
 Notes:
 - For `"id"` field syntax, see [Package ID Specifications] in the reference.
 
 [Package ID Specifications]: ../reference/pkgid-spec.html
 
 ## OPTIONS
 
 ### Output Options

diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1
@@ -36,8 36,8 @@ keeps metadata evolving without stagnation.
 .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
 fields are implementation details. For example, fields related to
 \[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"
@@ -333,6 333,12 @@ The JSON output has the following format:
 }
 .fi
 .RE
 .sp
 Notes:
 .sp
 .RS 4
 \h'-04'\(bu\h' 02'For \fB"id"\fR field syntax, see \fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html> in the reference.
 .RE
 .SH "OPTIONS"
 .SS "Output Options"
 .sp