rust-lang / rust-lang/reference

Guidelines for deprecated language features and intended future changes

Open
#2,038 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Authoring guide Meta
Dominant language
Rust
Stars
1.6k
Forks
607
PR merge metrics
PR metrics pending

Description

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:

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the author guide and the documented examples for local_inner_macros, future-incompatible warnings, expr.method.edition2021, and items.traits.params.patterns-no-body. Compare how these cases describe deprecations and future changes, including the linked historical trait-object documentation. Done means agreeing on and documenting consistent guidance for these cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.