Policy: Past behavior

[ehuss]

I'd like the authoring guide to have guidance on whether or not to include information about past versions of Rust. If we do allow it, what is the guidance for how to do that?

I would prefer to generally avoid references to older versions, but I acknowledge that there are some rare cases where it is truly helpful. Is there some nuance or balance for that?

rust-lang/spec#34 (comment) mentions that rfc3355 says:

The specification is specific to the latest version of Rust. [...]

While the specification might include notes about the Rust version that a feature was introduced in for informative purposes (similar to standard library documentation), it does not attempt to accurately specify older, unsupported versions of Rust.

The Vision blog post says:

The descriptive definitions tell the reader how a construct will behave with
respect to a specific Rust version (e.g. Rust 1.76).

[tshepang]

I would prefer to generally avoid references to older versions, but I acknowledge that there are some rare cases where it is truly helpful. Is there some nuance or balance for that?

what are some examples of those cases

[ehuss]

I don't know if these are actually good examples, but here's what we currently do:

• Note of why local_inner_macros exists: https://doc.rust-lang.org/1.90.0/reference/macros-by-example.html#r-macro.decl.hygiene.vis
• Note on mod.rs change: https://doc.rust-lang.org/1.90.0/reference/items/modules.html#r-items.mod.outlined.search-mod

There have been cases that have come up before, but I don't remember exactly what they were.

A year or two ago, Mara had a prototype that had something like this:

[tshepang]

am thinking Reference should be written as if the latest stable release of Rust is the only one that exists

• makes it more easy to read, without all the extra text
  • extra tooling would help with this, like "hide all version annotations"
• makes it more easy to maintain, which is hard enough already as it is, made worse by not having enough (adequate) contributors
• those on old Rust releases already have Reference of its time distributed with their toolchain (which of course does not have improvements latest Reference has, but then Project does not support anything other than latest Rust release anyway)