There has been some talk concerning auditing the Rust Reference for completeness in light of the new RFC: Require documentation for all new features. Some suggestions have been along the lines of adding references to undocumented RFCs in the reference and methodically documenting these features one by one. However, it has come to my attention that many of these RFCs seem to be outdated and no longer accurate – consider, for example the originating RFC for closures. Sure, we should give these pre-Rust 1.0 RFCs a break for living in a time of mass chaos (or so people tell me). However, I feel that it might be worth while taking a moment to clarify the purpose of an RFC after the RFC has been merged – a process being discussed in the Refining the RFC process posts.
Here are some thoughts that I have been discussing with a few people on IRC and would appreciate feedback.
I would like to reference what the Python community states with respect to maintaining PEPs (Python’s RFCs):
In general, Standards track PEPs are no longer modified after they have reached the Final state. Once a PEP has been completed, the Language and Standard Library References become the formal documentation of the expected behavior.
Informational and Process PEPs may be updated over time to reflect changes to development practices and other details. The precise process followed in these cases will depend on the nature and purpose of the PEP being updated.
I think we generally follow the first process – we haven’t always, but now post-Rust 1.0 I believe we can say with a good deal of confidence that RFCs that have been merged and then stabilized should no longer be changed. However, perhaps we should consider the ability the change process RFCs like the one mentioned previously: RFC: Require documentation for all new features.
However, there is a long period of time between merging and RFC and stabilizing an RFC and things change. Also, RFCs may be merged with unresolved questions. For this, I would like to propose that we
- Require RFCs to be updated prior to stabilization, ensuring accuracy and completeness.
- No unresolved questions should be allowed prior to stabilization
However, this requirement may not be not be as easy to adhere to as it sounds. A complication may arise in a situation where:
- An RFC is accepted and merged
- A feature is only partially stabilized
This is for example seen Implement revised coercion rules. I am under the opinion that this is perhaps a poor situation to be in, and would probably favor requiring the RFC to be split: One for what will be stabilized if only a partial stabilization is decided on and another for additional features that may be stabilized later.
I understand that many of my examples are pre-Rust 1.0, I just want to make sure we don’t follow this habit for post-Rust 1.0.
What purpose should we impose RFCs after they have been merged? Should they be maintained for historical purposes, or do they have a role in language standards and reference documentation? How should we maintain these RFCs? We should probably audit the RFCs before stabilization, but then how do we handle partial stabilization? Perhaps we shouldn’t allow that. Should we be able to modify process RFCs? And if so, how?