Skip to content

Attribute representation change in rustdoc JSON without version bump #140689

Closed

Description

@obi1kenobi

Rustdoc JSON is a public but unstable API, whose contract is that behavior changes are signaled by incrementing its embedded version number.

Unfortunately, rustdoc JSON format v45 appears to have suffered a behavior change without a corresponding version bump. This was caught by the test suites of cargo-semver-checks and its components, which used to pass on the initial nightly version where format v45 was released but no longer pass:
https://github.com/obi1kenobi/trustfall-rustdoc-adapter/actions/runs/14585442486/job/41627682245

Output {
         instantiated_name: "Clone",
         attrs: [
-            "#[automatically_derived]",
+            "#[automatically_derived]\n",
         ],
         canonical_path: [
             "core",
             "clone",

in rustc 1.88.0-nightly (13e879094 2025-05-04)

At a glance, this may have been due to #140606. It may be sufficient to strip the trailing whitespace at the time rustdoc JSON is created to recover the original behavior.

Activity

  1. added
    needs-triageThis issue may need triage. Remove when done. See docs forge.rust-lang.org/release/issue-triaging
    on May 6, 2025
  2. obi1kenobi commented on May 6, 2025

    @obi1kenobi
    MemberAuthor

    @rustbot label +A-rustdoc-json +T-compiler

  3. added
    T-compilerRelevant to the compiler team, which will review and decide on the PR/issue.
    on May 6, 2025
  4. added
    T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
    and removed
    T-compilerRelevant to the compiler team, which will review and decide on the PR/issue.
    needs-triageThis issue may need triage. Remove when done. See docs forge.rust-lang.org/release/issue-triaging
    on May 6, 2025
  5. self-assigned this
    on May 6, 2025
  6. aDotInTheVoid commented on May 6, 2025

    @aDotInTheVoid
    Member

    Short term, we can strip white space inside librustdoc, and get the old behaviour. I’ve got a patch locally that does this, I’ll make a PR once i describe it. It might still be worth bumping the format version, as v45 output might be buggy, but v46 output is good (even if v45 from before #140606 is the same as v45).

    Longer term, I’d like to make this less likely to happen again. We should probably add a triage or message on changes to tests/rustdoc-json informing PR authors/reviewers to be careful as this is a public API, and that if they want to change it, the FORMAT_VERSION also needs to be bumped. Not sure exactly what would be most useful to say here. CC @nnethercote @dtolnay, what would have been useful to see when reviewing #140606?

  7. dtolnay commented on May 6, 2025

    @dtolnay
    Member

    It should get an autoreview like what we do for Cargo.lock: #140535 (comment)

    Alona was pinged on the broken PR in #140606 (comment). But this comment is not enough for nnethercote or I to know what the review obligation is. Is there a bigger group to ping that would be more likely to intercept bad changes before landing? Some teams / working groups like clippy, miri, rust-analyzer, gcc, trait solver, and some other projects mention the team like this: #126893 (comment)

    I would recommend trying with just a more explanatory autoreview comment and see whether it gets improperly ignored.

  8. obi1kenobi commented on May 6, 2025

    @obi1kenobi
    MemberAuthor

    Not a rustdoc reviewer, but I'm happy to be pinged and participate if that's helpful — I've written parts of the rustdoc json test suite and I'm most likely to be downstream of breakage in it.

  9. aDotInTheVoid commented on May 7, 2025

    @aDotInTheVoid
    Member

    Opened #140762 for the format change, and #140773 for more pings and a message in triagebot.

    Is there a bigger group to ping that would be more likely to intercept bad changes before landing?

    I don't think so. Pinging all of T-Rustdoc seems excessive, as most of them don't work on rustdoc-json. I'll bring it up in the next T-Rustdoc meeting. Predrag offering to get pinged should be helpful though.

  10. added 2 commits that reference this issue on May 8, 2025
    18a61c1
    b62764b
  11. added 2 commits that reference this issue on May 8, 2025
    cd235bd
    526923a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

A-rustdoc-jsonArea: Rustdoc JSON backendC-bugCategory: This is a bug.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions