Remove apologies about the Reference #1792
Conversation
rustbot
added
the
S-waiting-on-review
traviscross
force-pushed
the
TC/remove-apologies
branch
from
c3ed844 to
d5c72e5
Compare
|
❤️ Hear hear. Much appreciation to all the contributors to the Reference. |
traviscross
force-pushed
the
TC/remove-apologies
branch
from
d5c72e5 to
6e62c00
Compare
traviscross
added
S-waiting-on-team
|
@rfcbot fcp merge |
|
Team member @tmandry has proposed to merge this. The next step is review by the rest of the tagged team members: 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! cc @rust-lang/lang-advisors: FCP proposed for lang, please feel free to register concerns. |
|
@rfcbot reviewed |
|
🔔 This is now entering its final comment period, as per the review above. 🔔 psst @tmandry, I wasn't able to add the |
traviscross
force-pushed
the
TC/remove-apologies
branch
from
6e62c00 to
baee89e
Compare
|
@rfcbot reviewed |
|
@rfcbot reviewed |
Right now the Reference, in its README and introduction, contains a number of warnings and caveats that amount to apologies about the document. These have outlived their usefulness and should be removed. The Reference is the reference on Rust. It's the product of an enormous amount of careful work by many people. It's a good document, and we don't need to apologize about it. In particular, these apologies don't need to be the very first things we say about the document. We don't need to warn people off from it. Given how we frame it at the moment, a reader could reasonably think, "well, if that's all its own authors think of this document, why should I waste my time with it?", and anecdotally, this is something that I've observed people reflecting back to us. Let's stop this negative cueing. Does the Reference have bugs or omissions? Sure. It always will. So does and will our compiler. We can simply point people to our issue tracker in a note; we don't need for this to be a warning, and we don't need to elaborate. Do we need to say the Reference is non-normative? No. We treat it with all the care and respect that we would any normative document, and we have for many years. We author it in normative language, and we take care to ensure that the substance of this normative language accords with normative lang team decisions. The lang team directly FCPs changes to the Reference when those changes affect the guarantees that are made by the language. Do we need to say that our descriptions of the language are "informal"? No, not in general. We work to describe things as precisely and correctly as we can. While such statements might not be "formal" ones, neither are they "informal". Do we need to say that it's not a specification? No. What is a specification anyway? We'd have to answer that before saying that it's not one. The Reference is the Reference. That's all we need to say. The text speaks for itself. Let's remove those things that have outlived their usefulness to us.
traviscross
force-pushed
the
TC/remove-apologies
branch
from
baee89e to
aca918d
Compare
|
While we're here, do we also want to take the opportunity to clarify what promises are made regarding forwards-compatibility? As demonstrated in discussions like this one, there continue to be cases where making breaking changes to the Reference is proposed. It would be good to clarify that It feels like this PR is the right place to add that language since this PR is already moving in the direction of changing the social contract of this document. |
|
It might be a good idea to document the language stability policy in the reference, but I would do that as a separate PR at this point. We reserve the right to make breaking changes when they are bug fixes. That can even extend to what's considered sound for unsafe code, but that would only happen when we consider the actual impact to be approximately zero or as a last resort. |
|
In addition to what @tmandry said, the Reference just documents the language. In such cases, it's the language, not the Reference per se, that's making a breaking change, and our latest RFC documenting our thinking on when that is acceptable is: |
rfcbot
added
finished-final-comment-period
to-announce
and removed
final-comment-period
labels
|
The final comment period, with a disposition to merge, as per the review above, is now complete. As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed. This will be merged soon. |
Right now the Reference, in its README and introduction, contains a number of warnings and caveats that amount to apologies about the document. These have outlived their usefulness and should be removed. The Reference is the reference on Rust. It's the product of an enormous amount of careful work by many people. It's a good document, and we don't need to apologize about it.
In particular, these apologies don't need to be the very first things we say about the document. We don't need to warn people off from it. Given how we frame it at the moment, a reader could reasonably think, "well, if that's all its own authors think of this document, why should I waste my time with it?", and anecdotally, this is something that I've observed people reflecting back to us.
Let's stop this negative cueing.
Does the Reference have bugs or omissions? Sure. It always will. So does and will our compiler. We can simply point people to our issue tracker in a note; we don't need for this to be a warning, and we don't need to elaborate.
Do we need to say the Reference is non-normative? No. We treat it with all the care and respect that we would any normative document, and we have for many years. We author it in normative language, and we take care to ensure that the substance of this normative language accords with normative lang team decisions. The lang team directly FCPs changes to the Reference when those changes affect the guarantees that are made by the language.
Do we need to say that our descriptions of the language are "informal"? No, not in general. We work to describe things as precisely and correctly as we can. While such statements might not be "formal" ones, neither are they "informal".
Do we need to say that it's not a specification? No. What is a specification anyway? We'd have to answer that before saying that it's not one.
The Reference is the Reference. That's all we need to say. The text speaks for itself. Let's remove those things that have outlived their usefulness to us.
cc @rust-lang/spec @rust-lang/lang