fix(metadata): Stabilize id format as PackageIDSpec

[epage]

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

[rustbot]

r? @ehuss

(rustbot has picked a reviewer for you, use r? to override)

[epage]

@rfcbot fcp merge

[rfcbot]

Team member @epage has proposed to merge this. The next step is review by the rest of the tagged team members:

• [x] @Eh2406
• [x] @Muscraft
• [x] @arlosi
• [ ] @ehuss
• [x] @epage
• [ ] @joshtriplett
• [x] @weihanglo

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[weihanglo]

@rfcbot reviewed

BTW, do we have a plan for SourceId?

[epage]

BTW, do we have a plan for SourceId?

I do not as I don't see as much reason to stabilize it. The end-user benefit here is that you can run a cargo command against a package you came across in cargo metadata. I don't see similar use cases at this time for SourceId.

[rfcbot]

:bell: This is now entering its final comment period, as per the review above. :bell:

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[weihanglo]

@bors r+

Thanks!

[bors]

:pushpin: Commit 63bb70df004e0097d1a084d88180d638c842b4c7 has been approved by weihanglo

It is now in the queue for this repository.

[bors]

:hourglass: Testing commit 63bb70df004e0097d1a084d88180d638c842b4c7 with merge 77f2da7b926008b7edcca2fcf6bf1ed4eee56872...

[bors]

:sunny: Test successful - checks-actions Approved by: weihanglo Pushing 77f2da7b926008b7edcca2fcf6bf1ed4eee56872 to master...