consider nudging people to document new features in the unstable book
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 119k
- Forks
- 16.1k
- PR merge metrics
- PR metrics pending
Description
Location
https://doc.rust-lang.org/nightly/unstable-book/
Summary
right now, when you add a new unstable feature, unstable-book-gen will parse it out of the source code and generate a stub such as https://doc.rust-lang.org/nightly/unstable-book/language-features/async-trait-bounds.html.
do we actually want this? it seems nice to instead encourage people to write docs for the new features they add. i am imagining something like this (see https://github.com/rust-lang/rust/blob/d3a2440384b54664dddd56e0081ca094c444e869/src/doc/unstable-book/README.md for how this differs from how things currently work):
- run unstable-book-gen as-is one last time. copy the generated SUMMARY.md to
src/doc/unstable-book, so it's tracked by git. - change unstable-book-gen to not overwrite SUMMARY.md, merely generate a local copy. then, give a hard error if its generated SUMMARY differs from the one tracked by git.
the second thing requires people to write their own docs, even if they're just a stub. and hopefully while people are at it, they will take the time to write more docs than just a stub.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read src/doc/unstable-book/README.md and inspect unstable-book-gen, starting by running the generator and comparing its generated SUMMARY.md with the tracked copy. Implement the workflow described in the issue: keep SUMMARY.md tracked, generate a local copy, and report an error when they differ. Done means new unstable features require corresponding entries in the unstable book.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100