@@ -5,15 +5,14 @@ editing the reference, fixing incorrect information, adding examples and
5
5
glossary entries, and documenting new or otherwise undocumented features in
6
6
Rust.
7
7
8
- For awhile, the Reference was basically ignored, and Rust continued gaining
9
- new features or changing old ones. It was also basically the introduction
10
- document before the first edition of the Rust book, and constantly in flux from
11
- the huge churn of the language design before v1.0.0. So there's a lot that's
12
- wrong, too teachy for people who should have basic understanding of Rust, or
13
- is too shallow for the Reference. As such, we
14
- have the warning saying there's work that needs to be done. Eventually, we plan
15
- to make sure everything is well documented enough that we can remove the
16
- warning.
8
+ For awhile, the Reference was basically ignored, and Rust continued gaining new
9
+ features or changing old ones. It was also basically the introduction document
10
+ before the first edition of the Rust book, and constantly in flux from the huge
11
+ churn of the language design before v1.0.0. So there's a lot that's wrong, too
12
+ teachy for people who should have basic understanding of Rust, or is too shallow
13
+ for the Reference. As such, we have the warning saying there's work that needs
14
+ to be done. Eventually, we plan to make sure everything is well documented
15
+ enough that we can remove the warning.
17
16
18
17
## Critiquing the Reference
19
18
@@ -54,7 +53,44 @@ threads and IO and we don't write about Rust in the future. Documentation is
54
53
written as if the current stable release of Rust is the last release. If you
55
54
want to write about Rust in the future, you want [ the Unstable book] [ unstable ] .
56
55
56
+ ## RFC Review Process
57
+
58
+ Older, stable RFCs need review to determine if they need documentation written
59
+ and, if so, need that documentation written. The [ "Document all features"] [ 9 ]
60
+ issue tracks the overall effort, and individual RFCs are laid out on the [ RFC
61
+ Status] project. RFCs that have not yet been reviewed to scope out the work are
62
+ in the "Needs Review" column, with ones needing documentation in the "Stable,
63
+ Needs Documentation" column.
64
+
65
+ If you review an RFC and determine that there is no documentation required,
66
+ please convert the project card to an issue and then close the issue, explaining
67
+ why no documentation is required. This is so as to ensure that there is a record
68
+ and a chance for others to disagree. If you review it and determine
69
+ documentation is necessary, feel free to simply move the card into the "Stable,
70
+ Needs Documentation" column. It can be converted into an issue if it needs
71
+ discussion, or left as a text card.
72
+
73
+ For RFCs which do not stabilize all at once (for instance, because some aspects
74
+ are insta-stable), if there is any unstabilized part that needs documentation,
75
+ then the RFC should be advanced to "Stable, Needs Documentation" and converted
76
+ to an issue. On the issue, remark about which parts need documentation and which
77
+ are still unstable.
78
+
79
+ ## Stabilization
80
+
81
+ Now, in order for a new RFC to be stabilized, it must have documentation
82
+ written. If this requires a change to the reference, then the necessary
83
+ documentation should be written and a PR created. Once the PR has been reviewed
84
+ (along with any necessary documentation PRs to other repositories), the feature
85
+ can be stabilized in Rust, and then the doc PRs merged. Anyone is free to write
86
+ these PRs, but they should wait until the feature is unlikely to change much
87
+ before stabilization.
88
+
89
+ RFCs needed documentation for stabilization can be added to the [ RFC Status]
90
+ project, under the "Awaiting Docs for Stabilization" column.
91
+
57
92
[ 9 ] : https://github.com/rust-lang-nursery/reference/issues/9
58
93
[ missing feature ] : https://github.com/rust-lang-nursery/reference/issues?q=is%3Aissue+is%3Aopen+label%3A%22Missing+Feature%22
59
94
[ playpen ] : https://play.rust-lang.org/
60
- [ unstable ] : https://doc.rust-lang.org/nightly/unstable-book/
95
+ [ unstable ] : https://doc.rust-lang.org/nightly/unstable-book/
96
+ [ RFC Status ] : https://github.com/rust-lang-nursery/reference/projects/1
0 commit comments