Life after an RFC

1

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:

  1. 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.

TL;DR

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?

1 Like
2

Python uses PEPs as part of the documentation. Rust RFCs are used to document and discuss proposed/in-dev/unstable features, but they don’t seem so great for final documentation to me (they contain motivation and lots of discussion which is not so relevant any more — at least, it’s not usually the first thing people want to see when looking up how a feature works). So I would assume RFCs are mainly used during development of the feature, with some tickets pointing at the RFC between acceptance and final implementation & documentation.

3

Just to be clear, Python PEPs contain an abstract, motivation, and rationale section as well; they also are used as the medium for proposing language features as far as I can tell which makes Python PEPs and Rust RFCs quite similar. The differences between the two is how we handle them after they a feature has stabilized:

  • Python will use their PEPs as reference documentation for a feature
  • Rust keeps the RFC for (fill in the blank here, but it seems like mostly for historical purposes)

Keeping RFCs for historical purposes is fine for the most part I suppose, by instead insisting reference documentation of features is found in the reference document. I just thought it might be worth clearing this up before a decision is made with the require documentation for all new features RFC.

1 Like
4

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.