Pre-RFC: Modify RFC 1636 to relax requirements for language features

1

Hi all! After being a little unhappy with the way that docs are required for language features, especially with regards to the upcoming epoch. As such, I want to get some discussion going before I make a formal RFC. So here it is!

Summary

Replace most of RFC 1636 with a requirement of opening issues for documentation for language features, rather than requiring that documentation land prior to stabilization. This will significantly un-burden the process for stabilizing a feature, while still ensuring documentation is written. Library requirements remain the same.

RFC 1636 has a noble goal; to make sure that everything is properly documented. From its motivation section:

At present, new language features are often documented only in the RFCs which propose them and the associated announcement blog posts. Moreover, as features change, the existing official language documentation (the Rust Book, Rust by Example, and the language reference) can increasingly grow outdated.

However, due to a few factors, the way this has worked out in practice is suboptimal. Reading closely, it hasn't even been implemented correctly. Quoting its text again:

Prior to stabilizing a feature, the features will now be documented as follows:

  • Language features:
    • must be documented in the Rust Reference.
    • should be documented in The Rust Programming Language.
    • may be documented in Rust by Example.
  • Standard library additions must include documentation in std API docs.
  • Both language features and standard library changes must include:
    • a single line for the changelog
    • a longer summary for the long-form release announcement.

Stabilization of a feature must not proceed until the requirements outlined in the How We Teach This section of the originating RFC have been fulfilled.

The changelog portion, for example, has not ever been done, to my knowledge.

Let's talk about what happens today when a new language feature is proposed. A pull request is opened against the book, the reference, Rust by Example (RBE), and possibly the Nomicon. Because these resources describe stable Rust, and the feature is not yet stable, these PRs will always fail CI, making it hard to know if the PR even works. Then, they sit until the feature is stabilized. Sometimes, last-minute things pop up in the compiler, meaning that the PR can sit open for a month or more. In fact, if someone wanted to be proactive about docs, this hurts even more, as the docs PR will be open for even longer. So the incentive becomes to do the docs at the absolute last minute, and make them as small as possible. Then, once the feature becomes stable, we can re-run CI, see if it's green, and merge the docs.

Furthermore, each resource has different requirements that makes this process akward:

The book

The book has its own train schedule, separate from Rust releases. The current in-progress edition of the book is written for Rust 1.21. To help with this, an appendix is added, so that some text can be added here to satisfy the documentation requirement for stabilization. However, this means that at a later time, Carol and/or myself have to do work to integrate this into the main text itself. So, while it technically exists, and is a helpful start, readers of the book won't even neccesarily see this feature as anything other than a blurb, and they won't become aware of it unless the specifically seek this index out.

The book is also not exhastive; some features aren't described, or are only partially described. This means that some stabilizations don't even require updating the book as-is today.

The reference

The reference is not a spec, but we try to also keep it to a high degree of quality when possible. Since it's not actually a spec, it's unclear to what degree features need to be documented in the reference, and so the incentive is to make it small. Once the reference turns into a spec, more work will be need to done to spell out everything in exacting detail; similar to the book, the documentation requirement doesn't ensure that the docs are good, just that they exist in some form.

Rust By Example and the nomicon

RBE and the nomicon are works that were adopted by the Rust docs team, and have little mini-teams forming around them to do work on them. However, they've always been a bit under-staffed, as it were. This can make getting timely reviews hard, and with the lack of high-level vision means it's not always clear what to put and where.

The actual proposal

So, given these issues, I propose instead that an issue is opened on each repository, specially tagged so that the docs team can be aware of the outstanding list at any given time. The text of the issue would be the text that previously would have been sent in as a PR.

This ensures that the status of docs for each feature is known, but doesn't lead to complex CI issues. It also means that it's still discoverable by users, we still have the same text as we would have had before, and we don't need to block things unneccesarily.

9 Likes
2

Oh, I forgot one more part: For TRPL, specifically, I would like to follow this model regarding the epoch features that are upcoming, even before this lands as an actual RFC.

Here’s the issue: TRPL second edition’s status is now semi-blocked on our editors, and therefore, not entirely under our control. We want to have a “TRPL: 2018 epoch edition”, to fulfill the docs requirements of the epoch. This creates an issue where the status of landing the features in time for the epoch becomes semi-blocked on the editors, which is not great.

Looking over the epoch features, I feel confident that, in the time before second editions’ text being firm enough to fork off for 2018 edition, and the 2018 epoch actually being released, I can do the work. Many features don’t require extensive modifications to the book; for example, NLL will amount to three or four lines of text being re-worked, to change the scopes that are being talked about. But since the book is so high-level, we don’t really get into the nitty-gritty details, and so overall, there’s not much change. This is not universally true for features, but I’m confident that it can be done. It’s just that, due to the schedules, it’s going to be a bit rear-loaded.

1 Like
3

One last thing: I forgot drawbacks.

The drawbacks, as I see it, are basically “what happens if these features are never documented.” I would argue, as I sorta did in the text, that even with the current policy, these features aren’t getting documented properly anyway, so it’s not like this is a major issue.

A second drawback would be that the issues are a bit harder to discover than the current appendix, with regards to the book. However, we can link to it from the book’s page, and explain the situation there.

4 Likes
4

It would be nice if each of these documentation end-points include an Appendix that specifically explains the PR/Issue process that is used to add new things to these documents. It would be nice if this Appendix linked or otherwise explained how to review the current in-flight issues/PR’s so that if someone is reading the document, it is easily discoverable the PR’s/Issues in-flight that they can review for documentation of items that may have been stabilized, but, the documentation not yet added to the official document.

EDIT: I think if each of the documents had such a section/appendix, it would largely address all of the drawbacks to your proposal rather cleanly.

2 Likes
5

That’s a fantastic idea. I’m kind of embarrassed it isn’t there already.

1 Like
6

I've been thinking of proposing the same thing. It's just really, really hard to keep track of "all the things" the way things are set up right now. I wasn't sure why that was, but your post has made me understand why I seem to always have such difficulty. In contrast, ensuring that an issue is open feels like something we can do.

4 Likes
7

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