The Reference needs to be more decisively sorted into Normative and Non-Normative statements.

[Lokathor]

At the moment:

• Every page of the Reference has a scary red banner that says "don't trust me".
• The Nomicon is expressly a no warranty, non-normative document.
• The Unsafe Code Guidelines is a WIP list of "recommendations" that, at best, will become RFC'd into the Reference, but again we can't trust the Reference because of the scary red banner.

This situation is not ideal, because it means that the default position of all of our core learning materials is "oh you can't actually rely on this". When people seemingly can't rely on anything at all they start to rely on rustc implementation details, or even just make things up out of "nowhere" as long as LLVM allows it (at least at the time). When enough people do this we get things like the Stabilize Drop Order RFC, which basically comes right out and says "we have to do this as is, even though we didn't get to make a real decision, or we break too much existing code".

Of course, there are statements spread throughout our teaching materials that align with actual normative statements about the Rust language, but anyone who isn't actually the lang team can't tell what's what. Obviously, it takes an immense amount of time and effort to work out an exact specification for how a language "really" works. I'm very sympathetic to this problem, and I don't expect it to be solved instantly. However, I think that with small steps useful progress can be made that will help the common user right away, without holding the lang team back from having the final say on each point (or at least as many of them as possible).

I propose that, as the Reference moves forward, an actually normative section of the book be started. It doesn't have to be a lot, it doesn't have to paint a whole picture of the langauge. It could be very small, a single bullet point even. All that matters is that it's marked as definitely something you can really trust. No scary red banner, just actual assertions about the Rust language. In time, more bullet points can be added to the normative section, and if it gets big enough it can spread into a multi-page chapter, until eventually (with enough time) the entire Reference can slowly flow from non-normative status to normative status.

Who Does The Work?

Finding actual normative statements that can be made about Rust would involve someone filing an issue to this repo:

• The lang team can, obviously, if they want to.
• The unsafe code guidelines wg will doubtlessly bump into things that are "locked in" as they investigate all the nooks of unsafe code.
• Probably any other sufficiently informed Rust user who can back up their claim with evidence can file an issue of what they think is a normative statement.

Once an issue with a normative statement is approved, it can be PR'd into the Reference in the normative section of the book.

Who Signs Off On Changes?

That's the double-edged sword of the proposal:

• The lang team still has final say to sign off on each and every element added to the normative section of the Reference.
• But that also means that the lang team has to take some time to approve each addition, which is a non-zero amount of time.

I expect that, initially, sorting normative from non-normative statements will be a bit of a drag, because you'll have to review a lot of "settled" issues. However, I think that you can consider this work an investment towards the eventual spec, and of course the Rust community at large will doubtlessly appreciate the increased trust that having a collection of official normative statements would bring to the language.

cc @Centril , @RalfJung

[RalfJung]

I agree having something normative is great! However, I am afraid that adding anything to that section would basically have to take the "slow path" and go through the RFC process. Anything else would shut out the community from the discussion about whether we really want this to be normative.

Any time the lang team "just decides" something, there's been a lot of backlash.

[Centril]

cc @ehuss
cc @jamesmunns (sealed Rust)
cc the rest of the language team: @nikomatsakis @withoutboats @scottmcm @pnkfelix @joshtriplett @withoutboats @cramertj

I wonder how best to handle this logistically in terms of the text...

• Should we have a new page with just bullets?
• Should we split the reference into a normative top level section and a non-normative one?
• Should we create a parallel normative spec which will eventually move everything from the reference into it?

Any time the lang team "just decides" something, there's been a lot of backlash.

I think the main idea here is to collect existing normative decisions into one document rather than to make new normative decisions which would need to go through the normal processes (RFCs / FCPs, language team meetings, etc. depending on the scale of the decision).

[joshtriplett]

On July 1, 2019 10:24:38 AM PDT, Mazdak Farrokhzad ***@***.***> wrote: cc @ehuss cc @jamesmunns (sealed Rust) cc the rest of the language team: @nikomatsakis @withoutboats @scottmcm @pnkfelix @joshtriplett @withoutboats @cramertj I wonder how best to handle this logistically in terms of the text... - Should we have a new page with just bullets? - Should we split the reference into a normative top level section and a non-normative one? - Should we create a parallel normative spec which will eventually move everything from the reference into it? > Any time the lang team "just decides" something, there's been a _lot_ of backlash. I think the main idea here is to collect existing normative decisions into one document rather than to make new normative decisions which would need to go through the normal processes (RFCs / FCPs, language team meetings, etc. depending on the scale of the decision).

Debian Policy uses an approach I like here: it carefully uses must/should/may in RFC style (without capitalization), and calls out informative sections, but keeps everything in one document.

[Lokathor]

@RalfJung, @Centril: Right. I didn't mean to say that things would become normative through sudden fiat. Rather that the lang team would have a second chance to sign off on things from previous RFCs that have passed, and that part of the future RFC process (which the lang team approves, as I understand it?) would be to sort out if the change that the RFC makes justifies adding anything to the normative section, probably as part of the "stabilization PR" final push for the feature.

[alercah]

Personally, I'd prefer that more work go into ensuring that the entire reference is a normative standard, rather than most of it being best-effort.

[Lokathor]

I think that's the same goal that issue is already about? If not could you please clarify.