Nightly 2022-09-06 fails, needs `rustdoc-types` v0.16.0 upgrade

[repi]

Otherwise fails in one of our crates on:

Error: Failed to parse rustdoc JSON
Caused by:
    invalid type: string "0:211:1559", expected adjacently tagged enum Type at line 1 column 253901

looks like a pretty small upgrade of the types.

stabilization of rustdoc json output can't come soon enough! :)

[Enselic]

Yep, rust-lang/rust#101462 was merged yesterday which changed the rustdoc JSON format. Todays nightly is the first nightly with the new format. This was also detected by the CI in this project which runs nightly for exactly this purpose: https://github.com/Enselic/cargo-public-api/runs/8220773135?check_suite_focus=true

This is now
Closed by #99
and released as https://github.com/Enselic/cargo-public-api/releases/tag/v0.18.0

Warning: Probably tomorrows nightly will have yet another incompatible change: rust-lang/rust#101521 (comment)

@Emilgardis You wanted to take care of doing the rustdoc JSON format bump next time (read: tomorrow), I think? Let me know if you would like me to do it, otherwise I will happily leave it up to you.

As a remark, we are not 100% independently able to adapt to rustdoc JSON format changes, we also depend on rustdoc_types crate to be updated: rust-lang/rustdoc-types@338e734

We could use our own fork, but I don't want to split the small rustdoc JSON community that has formed :)

@repi I agree it will be nice once rustdoc JSON hits stable :)
As a workaround, you can lock nightly AND cargo public-api to a fixed version. See https://github.com/Enselic/cargo-public-api/blob/main/docs/CI-EXAMPLES.md for an example.

[Emilgardis]

go ahead and do it @Enselic :)

[repi]

thanks!

and yup we had to pin to nightly-2022-09-05 both in our CI builds and locally for users in multiple (internal) repos which caused a bit of pain and config. but running nightly generally is best to have pinned to protect against changes and breakages anyway so was rather inevitable (until it is stabilised).

[aDotInTheVoid]

Gah, sorry for all the breakage recently. If you want nicer errors, cargo-semver-checks does a clever thing where it checks format_version, but only once the main deserialization has failed, so you don't error when the format change was minor enough not to appear in the output. source

And in regards to stability, even once all outstanding bugs are fixed, and we're totally satisfied with the format, docs, tests etc, I'm still not sure if we can be stable, while allowing adding new language constructs. I've wrote about this on zulip, and would love input on this.

Finally, rustdoc-types has just been published, containing format version 21, which has just landed on master

[Enselic]

Personally I don't mind the breakage much; this was what I signed up for when deciding to depend on nightly :) For now, I think freely evolving the rustdoc JSON format is more important than keeping it stable. Long term it would be nice with some form of stability, but we'll get there when we get there.

(I will repeat this on Zulip later so we can continue discussing there)

cargo-semver-checks does a clever thing where it checks format_version, but only once the main deserialization has failed, so you don't error when the format change was minor enough not to appear in the output. source

cargo-public-api also has this property actually. So if the generated rustdoc JSON is simple enough to not contain the incompatible change (e.g. if the incompatible change affected enums, but the crate does not contain enums), then cargo public-api will not error out either. cargo-public-api also only errors if there is a deserialization error; FORMAT_VERSION is always ignored.

Finally, rustdoc-types has just been published, containing format version 21, which has just landed on master

I have a proposal: Why don't we automate cargo publish of rustdoc-types? Should be pretty easy. Every night we check if there are changes, and do automatic version bump and automatic cargo publish if that is the case.

This repo has more or less fully automated cargo publish of crates. The trick to make it secure is to make use of GitHub orgs, because then if the cargo token leaks, it does still not allow taking over ownership of the crates no crates.io. My personal GitHub account actually has no active tokens, so there is no token that can leak that allows hostile takeover.

Note the Owners of https://crates.io/crates/cargo-public-api includes cargo-public-api/owners, which only has one member: https://github.com/EnselicCICD. Having a CI/CD account is BTW explicitly allowed by GitHub ToS.

I could help you set this up if you are interested. Reusing https://github.com/EnselicCICD would be the simplest by far, but if you want to set up your own org (mine is at http://github.com/cargo-public-api), that's of course perfectly fine. I think it would be great to have automated cargo publish of rustdoc-types, as it would make life simpler for both you and me/us :)

Some further reading: https://doc.rust-lang.org/cargo/reference/publishing.html

While they have permission to publish or yank versions of the crate, they do not have the ability to add or remove owners.

[aDotInTheVoid]

cargo-public-api also has this property actually. So if the generated rustdoc JSON is simple enough to not contain the incompatible change (e.g. if the incompatible change affected enums, but the crate does not contain enums), then cargo public-api will not error out either. cargo-public-api also only errors if there is a deserialization error; FORMAT_VERSION is always ignored.

Sorry I wasn't clear. cargo-semver-checks way still succeeds/fails in all the same cases, but the advantage is to create a relevent error that points to version mismatch, rather than some unactionable serde error.

I have a proposal: Why don't we automate cargo publish of rustdoc-types?

This sounds like a good idea. I don't think I want in to completely automaticly publish a new version every time rust-lang/rust/src/rustdoc-json-types changes, but doing some automation to generate a Issue or PR on change would be fastastic, I've filed rust-lang/rustdoc-types#18 to track this

[Enselic]

Sorry I wasn't clear. cargo-semver-checks way still succeeds/fails in all the same cases, but the advantage is to create a relevent error that points to version mismatch, rather than some unactionable serde error.

I agree it is a clever trick, but I actually prefer to shield my users from FORMAT_VERSION, because they have no clue what it is. Instead, I prefer to talk about nightly versions with my users. See https://github.com/Enselic/cargo-public-api#compatibility-matrix.

For reference, here is the error users see if their nightly is too new for cargo public-api to know how to parse:

Error: Failed to parse rustdoc JSON at "/Users/martin/src/cargo-public-api/target/doc/public_api.json".
This version of `cargo public-api` requires at least:

    nightly-2022-09-08

If you have that, it might be `cargo public-api` that is out of date. Try
to install the latest version with `cargo install cargo-public-api`. If the
issue remains, please report at

    https://github.com/Enselic/cargo-public-api/issues

Caused by:
    missing field `kind` at line 1 column 30120

Edit: I guess I could actually make the error message less speculative by also checking FORMAT_VERSION... I would be happy to review a PR for that :)

I've filed rust-lang/rustdoc-types#18 to track this

OK! I currently have a bit too much to do, but once I get time over I will be happy to assist.