fix(metadata): Stabilize id format as PackageIDSpec by epage · Pull Request #12914 · rust-lang/cargo (original) (raw)

What does this PR try to resolve?

For tools integrating with cargo, cargo metadata is the primary interface. Limitations include:

• There isn't an unambiguous way to map a package entry from cargo metadata to a parameter to pass to other cargo commands. An id field exists but it is documented as an opaque string, useful only for comparisons with other ids within the document.
• There isn't an unambiguous way of taking user parameters (--package) and mapping them to cargo metadata entries. cargo pkgid could help but it returns a PackageIdSpec which doesn't exist within the cargo metadata output.

This attempts to solve these problems by switching the id field from PackageId to PackageIdSpec which is a publicly documented format, can be generated by cargo pkgid, and is accepted by most commands via the --package flag.

As the "id" field is documented as opaque, this technically isn't a breaking change though people could be parsing it.

For cargo_metadata they do use a new type that documents it as opaque but publicly expose the inner String. The String wasn't publicly exposed due to a request by users but instead their PackageId type replaced using Strings in the API in oli-obk/cargo_metadata#59 with no indication given as to why the String was still exposed. However, you'll note that before that PR, they had WorkspaceMember that parsed PackageId. This was introduced in oli-obk/cargo_metadata#26 without a motivation given.

Note that PackageIdSpec has multiple representation that might uniquely identify a package and we can return any one of them.

Fixes #7267

How should we test and review this PR?

Additional information

cc @oli-obk