Guidelines for deprecated language features and intended future changes

[ehuss]

I think the author guide should have some guidance on referring to deprecated language features, and anything that is intended to change in the future.

There are several different ways this comes up:

• Future-incompatible-warnings, where something is intended to be changed in usually a breaking way.
• Future warnings about something that is intended to change in a future version or edition.
• Language features where it is recommended to not do something anymore.
• Changes that are planned for a future version (like unstable things, things in RFCs not yet implemented, etc.).

If there is a specific lint or issue, should it specify that lint or issue?

Similarly, if something is removed or changed in an Edition, should the Edition-specific docs mention that a particular thing is deprecated?

• ehuss's preference is to not mention that for Edition-specific changes. Non-edition changes are a bit more difficult to make a judgement on.

Some examples that are currently documented:

• local_inner_macros
• All the future-incompatible-warning stuff, which are (always?) in a note block.
• expr.method.edition2021 talks about possibly removing in the future.
• items.traits.params.patterns-no-body deprecated mut IDENTIFIER
• Gone now, but we used to say trait objects without dyn are not recommended: https://github.com/rust-lang/reference/blob/6a19ed33a80894adc2c1b49fdbb8a619c6f8be39/src/types/trait-object.md (search for "1.26").