Tracking issue for Rust 2024: Fix doctest `include` paths

[traviscross]

This is a tracking issue for fixing the path used for include in rustdoc doctests.

About tracking issues

Tracking issues are used to record the overall progress of implementation. They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions. A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature. Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Steps

• Implement in nightly Rust 2024.
  • rustdoc: make doctest span tweak a 2024 edition change #132210
• N/A: Implement migration lints.
• N/A: Add documentation to the reference.
  • See the instructions.
• Add documentation to the edition guide.
  • rustdoc: Fix doctest include paths edition-guide#329
• Ensure ready for Rust 2024 stabilization.

Unresolved Questions

• Should this be an edition item for Rust 2024?

Related

• regression: change in paths/CWD for rustdoc tests #132203
• rustdoc: use the correct span for doctests #130582
• rustdoc reports issues against lib.rs rather than an include_str!'d file #130470

cc @rust-lang/rustdoc @ehuss @notriddle @GuillaumeGomez

[notriddle]

I ran a grep over the Reference, and only https://doc.rust-lang.org/1.82.0/reference/input-format.html and https://doc.rust-lang.org/1.82.0/reference/attributes.html mention include_str!. I checked it off.

[notriddle]

@rfcbot fcp merge

Since the compiler can already auto-correct include! paths, I don't think this needs a migration lint. But if you disagree, and can come up with a way to make it work, please let me know!

[rfcbot]

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

• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @aDotInTheVoid
• @camelid
• @fmease
• @jsha
• @notriddle

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.

[ehuss]

I'd like to stress that we need to move quickly if we want to make this change. The crater run should have started a few weeks ago. We have the last edition PR going in as I write this, and we were planning to start the crater run today. Delaying for this is stressing our timeline.

I would encourage considering the forward-compatible warning approach suggested in #132210 (comment) as a way to simplify the problem and the code, since you won't need to retain the arguably old broken behavior. (Or, just accept the breakage in #132203 and help those packages fix their tests.)

Can the rustdoc team focus on getting this resolved and merged within a few days? I would prefer to not delay for something last minute like this.

[traviscross]

Given the timeline, and building on what @ehuss said, here are the questions and items probably most in need of focus:

1. Might the @rust-lang/rustdoc team just accept the breakage in Rust 1.83?
   • This is arguably a bug-fix, which is normally allowed breakage.
   • The number of crates affected is not large.
   • Unlike other forms of breakage we worry a lot about, this does not affect the dependency graph or whether the program works.
2. If the team does want this to be an edition item, then please:
   • Post the chapter to the edition guide tomorrow (cc @notriddle).
   • While the FCP can continue, in the interest of time we need a presumptive decision by the team lead about the direction here. I.e., @GuillaumeGomez, if this is an ask for an edition item, please confirm that's the direction you want to go.
   • With the edition guide done and that presumptive decision, we'll merge rustdoc: make doctest span tweak a 2024 edition change #132210, which will allow us to go ahead with our edition crater runs.

[notriddle]

I would encourage considering the forward-compatible warning approach suggested

The problem is that the only way to get rid of the warning is to bump the edition, or to stop using include_bytes! in your README examples, or to stop using #![doc=include_str!("../README.md")] to test your README examples. There's no localized fix to make the code work both before and after the compiler change at the same time.

This is also why I'd rather not just accept the breakage. There's no way for the affected crates to fix nightly without breaking stable.

Post the chapter to the edition guide tomorrow

rust-lang/edition-guide#329

[GuillaumeGomez]

I confirm this is the direction I want to go. I'm surprised an FCP is needed here though but I trust @notriddle's judgement. Let's try to get it approved by tomorrow.